|
Oracle® HTTP Server Administering a Standalone Deployment Based on Apache 1.3
10g Release 2 (10.1.2) B14008-02 |
|
 Previous |
 Next |
|
Oracle® HTTP Server Administering a Standalone Deployment Based on Apache 1.3
10g Release 2 (10.1.2) B14008-02 |
|
|
Previous |
Next |
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 Application Server 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. |
Table 7-1 lists all the Oracle HTTP Server modules discussed in this chapter.
Controls access to the server based on characteristics of a request, such as hostname or IP address.
Enables manipulation of URLs in processing requests. It provides mapping between URLs and file system paths, and URL redirection capabilities.
Enables anonymous user access to protected areas (similar to anonymous FTP, where the email addresses can be logged).
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.
Allows reverse proxies that terminate SSL connections in front of Oracle HTTP Server, such as OracleAS Web Cache, 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 is an Oracle module.
It also allows certain requests to be treated as HTTPS requests even though they are received through HTTP. This is done using the SimulateHttps and AddCertHeader directives.
SimulateHttps takes the container it is contained within, such as <VirtualHost>, <Location>, and so on, and treats all requests received for this container as if they were received through HTTPS, regardless of the real protocol that the request was received through.
AddCertHeader is specifically for use with Oracle Application Server Web Cache. For Oracle Application Server Web Cache, it adds a special header that indicates to Oracle HTTP Server which requests Oracle Application Server Web Cache received through HTTPS. mod_certheaders triggers Oracle HTTP Server to only treat those cases where Oracle Application Server Web Cache received the request as HTTPS as if Oracle HTTP Server received it through HTTPS.
Perform the following steps to configure mod_certheaders:
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
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 |
|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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.
If OracleAS Web Cache is being used as the load balancer, it sends an HTTP header that identifies all requests it received through HTTPS. This means that mod_certheaders automatically detects which requests should be treated as HTTPS requests by simply looking for this header. To enable this, add the following directive to httpd.conf:
AddCertHeader HTTPS
This affects all URLs processed by Oracle HTTP Server.
For other 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/.
Edit the $ORACLE_HOME/sso/conf/sso_apache.conf, and comment out the following line:
#SSLOptions +ExportCertData +StdEnvVars
Runthe following command:
dcmctl updateconfig -ct ohs
Run the following command:
opmnctl restartproc type=ohs
Test that the SSO server can be logged into with client authentication.
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 Extended API (EAPI). Oracle HTTP Server always has EAPI-enabled.
This module is available on UNIX systems only.
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.
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/
Enables you to monitor performance of site components with Oracle's Dynamic Monitoring Service (DMS). It is an Oracle module.
Enables you to control the environment for CGI scripts and SSI (Server Side Includes) pages by passing, setting, and unsetting environment variables.
ModifyEnv appends or prepends a value to an existing ENV variable's value, and passes it into the Oracle HTTP Server environment. The following is the usage:
Let $FOO = "foo":
ModifyEnv FOO "bar" modifies the value of $FOO from "foo" to "foo:bar"
ModifyEnv FOO "+bar" modifies the value of $FOO from "foo" to "bar:foo"
Let $FOO be undefined:
Modify Foo "bar" sets the value of $FOO to "bar"
Provides examples and guidance on how to write modules using the Apache API. When implemented, it demonstrates module callbacks triggered by the server.
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.
Supports the FastCGI protocol, which enables you to maintain a pool of running servers for CGI applications, thereby eliminating start-up and initialization overhead.
Provides a filter that processes documents for SSI (Server Side Includes) directives.
Summarizes the entire server configuration, including all installed modules and directive settings.
Enables logging of client user agents. It is deprecated; you should use mod_log_config instead of mod_log_agent.
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.
Enables logging of documents that reference documents on the server. It is deprecated; you should use mod_log_config instead of mod_log_referer.
Enables the server to determine the type of a file from its filename, and associate files with handlers for processing.
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.
Maps a list of files into memory, useful for frequently requested files that are not changed often.
Enables the server for content negotiation (selection of documents based on the client's capabilities).
Routes requests from the Oracle HTTP Server to Oracle Application Server Containers for J2EE (OC4J), through the AJP 1.3 protocol. It is an Oracle module.
mod_oc4j is enabled by default. During installation, the oc4j_deploy_tool.jar adds mount points to mod_oc4j.conf for applications deployed into OC4J instances. Requests that come in for specific mount points in mod_oc4j are routed to the OC4J instance for that mount point.
OC4J instances are started and managed by Oracle Process Manager and Notification Server (OPMN).
This section discusses the following topics:
The following sections describe all relevant directives in httpd.conf and mod_oc4j.conf. Sample configurations are also provided.
The mod_oc4j directives are maintained in mod_oc4j.conf. The mod_oc4j.conf file is included by default into the httpd.conf file, using the following directive:
include "ORACLE_HOME/Apache/Apache/conf/mod_oc4j.conf"
The following directives are used to configure mod_oc4j:
Loads the mod_oc4j module.
| Category | Value |
|---|---|
| Syntax | LoadModule oc4j_module mod_oc4j shared library file
|
| Required | Yes |
| Default |
|
| Example |
|
Specifies the size of the OC4J connection cache.
| Category | Value |
|---|---|
| Syntax | Oc4jCacheSize <size of connection cache>
|
| Required | No |
| Default |
|
| Example | Oc4jCacheSize 64
|
| Usage | Specifies the number of concurrent OC4J connections that can be cached by each Oracle HTTP Server process. Setting this directive to "0" will disable persistent connections between mod_oc4j and the OC4J instances.
|
Defines maximum idle time (in seconds) for unused connections.
| Category | Value |
|---|---|
| Syntax | Oc4jConnTimeout <timeout value for AJP13 connections>
|
| Required | No |
| Default | None |
| Example | Oc4jConnTimeout 10
|
| Usage | Useful for cases where there is a firewall between mod_oc4j and OC4J that times out connections. The value should be set to a value smaller than the timeout value used by the firewall.
|
Directs mod_oc4j to use JSESSIONID_<cookie_name_extension> as OC4J's session identifier in the cookie.
| Category | Value |
|---|---|
| Syntax | Oc4jCookieExtension <cookie_name_extension>
|
| Required | No |
| Default | None |
| Example | Oc4jCookieExtension MYEXT
|
| Usage | Directs mod_oc4j to use JSESSIONID_<cookie_name_extension> as OC4J's session identifier in the cookie, instead of JSESSIONID. In the preceding example, JSESSIONID_MYEXT is used as the OC4J's session identifier.
|
Governs passing SSL environment variables.
| Category | Value |
|---|---|
| Syntax | Oc4jExtractSSL On|Off
|
| Required | No |
| Default | Off
|
| Example | Oc4jExtractSSL On
|
| Usage | Directs mod_oc4j to decide whether or not to pass three SSL environment variables, SSL_CLIENT_CERT, SSL_CIPHER, and SSL_SESSION_ID to OC4J. There is a performance cost associated with copying the SSL environment variables to OC4J, so set it to "On" only if the environment variables must be available to OC4J.
|
Directs mod_oc4j to pass some environment variables from Oracle HTTP Server to OC4J.
| Category | Value |
|---|---|
| Syntax | Oc4jEnvVar environment variable name [environment variable default value]
|
| Required | No |
| Default | None |
| Example | Oc4jEnvVar MY_ENV1
|
| Usage | For each OC4jEnvVar entry, you must also configure the Oracle HTTP Server directive, PassEnv, with the environment variable. Otherwise, mod_oc4j cannot acquire and pass the value.
Multiple entries are allowed. You could specify the default value for the environment variable as the second parameter, or leave it empty. If the environment variable's value is found in the Oracle HTTP Server environment, its value will be passed to OC4J. Otherwise, if the default value is set, the default value will be passed. If this environment variable's value is not found in the Oracle HTTP Server environment and the default value is not set, nothing is passed to OC4J. There is a performance degradation associated with |
Directs mod_oc4j to route requests containing a particular path to a destination. A destination can be a single OC4J process, or a set of OC4J instances.
| Category | Value |
|---|---|
| Syntax | Oc4jMount path [destination]
where path is the context root. The path parameter must be the same as the application context root specified in the OC4J configuration file xxx <default-web-app application="default" name="defaultWebApp" root="/j2ee"/> and where destination is one of these types:
If destination is not specified, the default OC4J instance name of
provides the same result as:
|
| Required | No |
| Default | None |
| Examples | Oc4jMount /app01/* ajp13://my-sun:8888
|
| Usage | Examples are provided for each routing destination:
A request with the pattern specified in path is routed to an OC4J process listening on my-sun, port 8888 with the AJP 1.3 protocol. (my-sun and port 8888 are the AJP 1.3 protocol host and port specified in the OC4J configuration file xxx
A request with the pattern specified in path is load balanced to one or more of the OC4J instances specified (instances are separated by commas). The Oracle Application Server Cluster Name is optional. If it is provided, the destination OC4J instance should be inside the named cluster. If none is provided, the destination OC4J instance should be inside the local Oracle Application Server cluster.
A request with the pattern specified in <path> is load balanced to one or more of the OC4J instances specified (instances are separated by commas). The host name is optional. If it is provided, the destination OC4J instance should be inside the Oracle Application Server instance residing on that host. If none is provided, the destination OC4J instance could be on any host. |
Copies mount points from the base server.
| Category | Value |
|---|---|
| Syntax | Oc4jMountCopy On|Off
|
| Required | No |
| Default | On |
| Example | Oc4jMountCopy Off
|
| Usage | Directs mod_oc4j to decide whether to copy Oc4jMount points from the base server to the virtual host on which this directive is specified. If its value is On, all of the Oc4jMount points configured in the base server will be copied to the virtual host. If its value is Off, only the Oc4jMount points configured within the virtual host scope will be used.
|
Allows users to configure an error range using Oracle HTTP Server's error pages when errors in the range are returned from OC4J.
| Category | Value |
|---|---|
| Syntax | Oc4jUseOHSErrors On|Off/min-max
|
| Required | No |
| Default | off |
| Example | OC4jUseOHSErrors 400-410
|
| Usage | Oc4jUseOHSErrors Off: This is the default value if Oc4jUseOHSErrors is not specified. OC4J error pages are passed back to the client for all error values.
|
This section provides some sample configurations for mod_oc4j.
Example 7-1 Sample mod_oc4j configuration
This configuration mounts all requests starting with the URI /servlet/ to the default instance of OC4J processes.
Make this entry in the httpd.conf file:
Oc4jMount /servlet/*
Example 7-2 Sample mod_oc4j configuration
This configuration performs the same work as the configuration in Example 7-1, using a <Location> container directive instead of the Oc4jMount directive.
Make this entry in the httpd.conf file:
<Location /servlet>
SetHandler oc4j-handler
</Location>
|
Note: This will only route requests to default the OC4J instance |
Example 7-3 Sample mod_oc4j configuration
This configuration mounts all requests starting with the URI /servlet/ or /j2ee/ and all JSP pages to the default OC4J instance of OC4J processes.
Make these entries in the mod_oc4j.conf file:
Oc4JMount /servlet/* Oc4JMount /*.jsp Oc4JMount /j2ee/*
All requests starting with the URI /applicationA/ and all JSP pages to oc4j_instance_A, in which all OC4J processes are managed by OPMN.
All requests starting with the URI /applicationB/ to oc4j_instance_B, in which all OC4J processes are managed by OPMN.
Make these entries in the mod_oc4j.conf file:
Oc4JMount /applicationA/* oc4j_instance_A Oc4JMount /applicationB/* oc4j_instance_B Oc4JMount /j2ee/* Oc4JMount /*.jsp oc4j_instance_A
mod_oc4j load balancing, including metric based load balancing, is discussed in detail in Appendix A, "Load Balancing Using mod_oc4j".
Optionally, you can have direct SSL support for communication between mod_oc4j and OC4J. To do this, you have to enable SSL on the mod_oc4j side as well as the OC4J side.
Add the following directives in mod_oc4j.conf to enable SSL for mod_oc4j:
Indicates whether mod_oc4j needs to use SSL when communicating with OC4J processes. It should not be configured to "On" if Oc4jiASPTActive is configured to "On".
| Category | Value |
|---|---|
| Parameter Name | Oc4jEnableSSL
|
| Parameter Type | string |
| Valid Values | On/Off
|
| Default Value | Off
|
When Oc4jEnableSSL is set to "On", this directive specifies the location of an Oracle Wallet file that contains SSL certificates that are used for SSL communication with OC4J processes.
| Category | Value |
|---|---|
| Parameter Name | Oc4jSSLWalletFile
|
| Parameter Type | string |
| Valid Values | Path to a wallet directory location that contains the SSL certificate to be used when establishing SSL connections to OC4J processes. |
| Default Value | N/A |
When Oc4jEnableSSL is set to "On", this value is the obfuscated password used for authentication when opening the wallet file. This value is obtained using the utility provided with the Oracle Wallet Manager.
| Category | Value |
|---|---|
| Parameter Name | Oc4jSSLWalletPassword
|
| Parameter Type | string |
| Valid Values | Obfuscated password used for authentication when opening the wallet file specified by Oc4jSSLWalletFile. |
| Default Value | N/A |
|
Note: Wallet passwords have been deprecated. A warning message is generated in the Oracle HTTP Server log if this directive is used. For secure wallets, Oracle recommends that you get a SSO wallet instead. Refer to the Oracle Application Server Security Guide for information on SSO wallet. |
To enable SSL communication between mod_oc4j and OC4J, you have to enable SSL on the OC4J side too.
|
See Also: Oracle Application Server Containers for J2EE Security Guide for enabling SSL on the OC4J side. |
This module provides integration support with Oracle Notification Service (ONS) and Oracle Process Manager and Notification Server (OPMN). It is an Oracle module.
mod_onsint provides the following functionality:
Provides a subscription mechanism for ONS notifications within Oracle HTTP Server. This is particularly important on UNIX where Oracle HTTP Server employs a multi-process architecture. In such an architecture, it is not feasible to have an ONS subscriber in each process since there are up to 8192 processes that comprise a single Oracle HTTP Server instance. Instead, mod_onsint provides a single process that receives notification for all modules within an Oracle HTTP Server instance.
Publishes PROC_READY ONS notifications so that other components such as OPMN and OC4J are notified that the listener is up and ready. It also provides information such as DMS metrics and information about how the listener can be contacted. These notifications are sent periodically by mod_onsint as long as the Oracle HTTP Server instance is running.
Provides functionality that allows Oracle HTTP Server to terminate as a single unit if the parent process fails. The parent process is responsible for starting and stopping all of the child processes for an Oracle HTTP Server instance. The failure of the parent process without first shutting down the child processes leaves Oracle HTTP Server in an inconsistent state that can only be fixed by manually killing all of the orphaned child processes. Until this is done, a new Oracle HTTP Server instance cannot be started since the orphaned child processes still occupy the ports Oracle HTTP Server wants to use. mod_onsint provides a monitor of the parent process. If it detects that the parent process has died, it kills all of the remaining child processes. When combined with OPMN, this provides restartability for Oracle HTTP Server in the case of a parent process failure. mod_onsint ensures that all of the Oracle HTTP Server child processes die, leaving the ports open for a new Oracle HTTP Server instance. OPMN ensures that a new instance is started once the failure of the original instance is detected.
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.
There is an optional directive called OpmnHostPort that can be configured for mod_onsint. 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. 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.
This Oracle module (an OCI application written in C) is an extended implementation of mod_dav, and is integrated with the Oracle HTTP Server. mod_oradav can read and write to local files or to an Oracle database. The Oracle database must have an OraDAV driver (a stored procedure package) that mod_oradav calls to map WebDAV activity to database activity. Essentially, mod_oradav enables WebDAV clients to connect to an Oracle database, read and write content, and query and lock documents in various schemas.
You can configure mod_oradav to an Oracle database using standard Oracle HTTP Server directives. mod_oradav can immediately leverage other module code (such as mime_magic) in order to perform content management tasks. Most OraDAV processing activity involves streaming content to and from a content provider; and mod_oradav uses OCI streaming logic directly within the Oracle HTTP Server.
To configure mod_oradav, you enter parameters within a <Location> container directive in httpd.conf. The <Location> container directive specifies the DAV-enabled URL. The DAV keyword is followed by a single value: On, which tells mod_dav to use the local file system for content.
The following example specifies that the directory myfiles under the Web server documents directory (htdocs by default) is to be DAV-enabled, along with all directories under myfiles in the hierarchy. (Note that there must not be any symlinks defined on myfiles or any of its subdirectories.)
<Location /myfiles> DAV On </Location>
For information about using mod_oradav to access database schemas for access by third-party tools (such as Adobe GoLive and Macromedia Dreamweaver) and Oracle interMedia, refer to the OraDAV information available on OTN at
http://www.oracle.com/technology/index.html
Enables strong cryptography for Oracle HTTP Server. This Oracle module 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.
Enables single sign-on for Oracle HTTP Server. mod_osso examines incoming requests and determines whether the resource requested is protected, and if so, retrieves the Oracle HTTP Server cookie for you. It is an Oracle module.
Embeds the Perl interpreter into the Oracle HTTP Server. This eliminates start-up overhead and enables you to write modules in Perl. Oracle Application Server uses Perl version 5.6.1.
This section provides information for mod_perl users working with databases. It explains how to test a local database connection and set character forms.
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 Application Server. 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:
Edit httpd.conf using a text editor.
Search for "PerlModule Apache::DBI".
Uncomment the line PerlModule Apache::DBI".
Restart Oracle HTTP Server using the following command:
UNIX: ORACLE_HOME/opmn/bin> opmnctl [verbose] restartproc ias-component=HTTP_Server
Windows: ORACLE_HOME\opmn\bin> opmnctl [verbose] restartproc ias-component=HTTP_Server
Files must be copied to ORACLE_HOME/Apache/Apache/cgi-bin
Example 7-5 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>.
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-6 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 ######
SQL NCHAR datatypes have been refined since 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 aboutSQL 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-7 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-7, 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.
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-8 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' );
PHP (recursive acronym for "PHP: Hypertext Preprocessor") is an open source, widely-used, general-purpose, client-side scripting language, that is embedded in standard HTML. It is used to generate dynamic HTML pages. On Oracle HTTP Server, PHP support is provided through mod_php and has Oracle database support enabled. It uses PHP version 4.3.9.
|
Note: phpinfo() prints out very sensitive information about the current state of PHP and Oracle HTTP Server intervals. Users new to PHP, or those who are unaware of phpinfo() should not inadvertantly leave a PHP script called phpinfo() publically accessible.
|
|
See Also:
|
Connects the Oracle HTTP Server to an Oracle database, enabling you to create Web applications using Oracle stored procedures. It is an Oracle module.
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.
Any PL/SQL Application written using the PL/SQL Web ToolKit
Oracle Application Server Portal
Perform the following steps to create a DAD:
Edit the DAD configuration file ORACLE_HOME/Apache/modplsql/conf/dads.conf.
Add a DAD where the DAD has the following format:
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 ofmod_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.
|
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
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
One or more mod_plsql specific directives. For example:
PlsqlDatabaseUsername scott PlsqlDatabasePassword tiger PlsqlDatabaseConnectString orcl PlsqlAuthenticationMode Basic
An Oracle HTTP Server </Location> directive which closes the group of directives for the named Location, and defines a single DAD.
Save the edits.
Obfuscate the DAD password by running the "dadTool.pl" script located in ORACLE_HOME/Apache/modplsql/conf.
Restart the Oracle HTTP Server for the configuration to take effect.
UNIX: ORACLE_HOME/opmn/bin> opmnctl [verbose] restartproc ias-component=HTTP_Server
Windows: ORACLE_HOME\opmn\bin> opmnctl [verbose] restartproc ias-component=HTTP_Server
You can create additional DADs by defining other uniquely named Locations in dads.conf.
mod_plsql configuration parameters reside in the following three configuration files:
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.
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.
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 Application Server mod_plsql User's Guide for details on caching functionality inmod_plsql.
|
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"
Multi-line directives enable you to specify same directive multiple times in a DAD.
Table 7-3 mod_plsql Configuration Files and Parameters
| Configuration File | Parameters |
|---|---|
|
|
PlsqlIdleSessionCleanupInterval |
|
|
PlsqlRequestValidationFunction |
|
|
|
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 toplsql.README located in ORACLE_HOME/Apache/modplsql/conf for detailed description of plsql.conf.
|
The following parameters that can be specified in plsql.conf:
Enables Dynamic Monitoring Service (DMS) for mod_plsql.
| Category | Value |
|---|---|
| Syntax | PlsqlDMSEnable On/Off
|
| Default | On |
| Example | PlsqlDMSEnable On
|
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:
UNIX: ORACLE_HOME/Apache/modplsql/logs
Windows: ORACLE_HOME\Apache\modplsql\logs
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
|
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
|
This file contains the configuration parameters for the PL/SQL Database Access Descriptor (DAD).
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:
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
|
For all purposes, except for debugging, this parameter should be omitted. You could use this parameter to stop SQL Trace/SQL Profiling.
In older versions of the product, this parameter was called after_proc.
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
|
For all purposes, except for debugging, you should leave this parameter set to "Off".
In older versions of the product, this parameter was called always_desc.
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
|
Most customer applications use Basic Authentication. Custom Authentication modes (GlobalOwa, CustomOwa, PerPackageOwa) are used by very few PL/SQL applications. The SingleSignOn mode is supported only for Oracle Application Server releases, and is used by OracleAS Portal and OracleAS Single Sign-On.
If the DAD is not using the Basic authentication, then you must include a valid username/password in the DAD configuration. For the Basic mode, if you wish to perform dynamic authentication, the DAD username/password parameters must be omitted.
In older versions of the product, this configuration parameter was derived from a combination of enablesso and custom_auth.
enablesso = Yes translates to PlsqlAuthenticationMode SingleSignOn
custom_auth = Global translates to PlsqlAuthenticationMode GlobalOwa
custom_auth = Custom translates to PlsqlAuthenticationMode CustomOwa
custom_auth = PerPackage translates to PlsqlAuthenticationMode PerPackageOwa
All other combinations translate to Basic.
|
See Also: "Securing Application Database Access throughmod_plsql" chapter in the Oracle Application Server mod_plsql User's Guide for more information regarding different authentication modes.
|
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
|
For all purposes, except for debugging purposes, this parameter should be omitted. You could use this parameter to start SQL Trace/SQL Profiling.
In older versions of the product, this parameter was called before_proc.
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
|
This parameter is relevant only if you are using procedures with array parameters, and passing varying number of parameters to the procedure.
The default should be sufficient for most PL/SQL applications.
To see if this parameter needs to be changed, check the number of versions of a SQL statement in the SQL area.
Consider using flexible parameter passing to reduce the problem.
In older versions of the product, this parameter was called bind_bucket_lengths.
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
|
This parameter is relevant only of you are using procedures with array parameters, and passing varying number of parameters to the procedure.
The default should be sufficient for most PL/SQL applications.
To see if this parameter needs to be changed, check the number of versions of a SQL statement in the SQL area.
Consider using flexible parameter passing to reduce the problem.
In older versions of the product, this parameter was called bind_bucket_widths.
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 |
|
Environment variables added here are available in the PL/SQL application through the function owa_util.get_cgi_env.
In older versions of the product, this parameter was called cgi_env_list.
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 OracleAS Portal. In such situations, if you are running mod_plsql against a pre-9.0.2 version of OracleAS Portal, this should be set to 1.
| Category | Value |
|---|---|
| Syntax | PlsqlCompatibilityMode BitFlag
|
| Default | 0 |
| Example | PlsqlCompatibilityMode 1
|
This parameter enables an old bug in mod_plsql in which mod_plsql incorrectly converted the plus symbol (+) to space characters for document downloads. Enabling the first bit in this flag will make it impossible to download documents that have a plus symbol (+) in the document name.
Specifies the timeout in milliseconds for testing a connection pooled in mod_plsql.
When PlsqlConnectionValidation is set to "Automatic" or "AlwaysValidate", mod_plsql will attempt to test pooled database connections. This parameter specifies the maximum time mod_plsql should wait for the test request to complete before it assumes that the connection is not usable.
| Category | Value |
|---|---|
| Syntax | PlsqlConnectionTimeout 5000
|
| Default | 10000 |
| Example | PlsqlConnectionTimeout 5000
|
Specifies the mechanism mod_plsql should use to detect dead connections in its connection pool.
For performance reasons, mod_plsql pools database connections. If a database instance goes down, and mod_plsql was maintaining a pool of connections to the instance, then each pooled database connection results in an error when it is next used to service a request. This can be a concern in high availability configurations like RAC where even if one node goes down, other nodes servicing the database might have been able to service the request successfully. mod_plsql provides for a mechanism whereby it can self-correct after it detects a failure that could be caused by a database node going down. This mechanism to self-correct is controlled by the parameter PlsqlConnectionValidation.
The following are the valid values for PlsqlConnectionValidation:
Automatic: mod_plsql tests all pooled database connections which were created prior to the detection of a failure that could mean an instance failure.
ThrowAwayOnFailure: mod_plsql throws away all pooled database connections which were created prior to the detection of a failure that could mean an instance failure.
AlwaysValidate: mod_plsql always tests all pooled database connections which were created prior to issuing a request. Since this option has an associated performance overhead for each request, this should be used with caution.
NeverValidate: mod_plsql never pings any pooled database connection. This option always for older behavior in mod_plsql.
| Category | Value |
|---|---|
| Syntax | PlsqlConnectionValidation Automatic/ThrowAwayOnFailure/AlwaysValidate/NeverValidate
|
| Default | Automatic
|
| Example | PlsqlConnectionValidation ThrowAwayOnFailure
|
When mod_plsql encounters one of the following errors, it assumes that the database might have been down.
00443, 00000, "background process did not start"
00444, 00000, "background process failed while starting"
00445, 00000, "background process did not start after x seconds"
00447, 00000, "fatal error in background processes"
00448, 00000, "normal completion of background process"
00449, 00000, "background process unexpectedly terminated with error"
00470, 00000, "LGWR process terminated with error"
00471, 00000, "DBWR process terminated with error"
00472, 00000, "PMON process terminated with error"
00473, 00000, "ARCH process terminated with error"
00474, 00000, "SMON process terminated with error"
00475, 00000, "TRWR process terminated with error"
00476, 00000, "RECO process terminated with error"
00480, 00000, "LCK* process terminated with error"
00481, 00000, "LMON process terminated with error"
00482, 00000, "LMD* process terminated with error"
00484, 00000, "LMS* process terminated with error"
00485, 00000, "DIAG process terminated with error"
01014, 00000, "ORACLE shutdown in progress"
01033, 00000, "ORACLE initialization or shutdown in progress"
01034, 00000, "ORACLE not available"
01041, 00000, "internal error. hostdef extension doesn't exist"
01077, 00000, "background process initialization failure"
01089, 00000, "immediate shutdown in progress- no operations permitted"
01090, 00000, "shutdown in progress- connection is not permitted"
01091, 00000, "failure during startup force"
01092, 00000, "ORACLE instance terminated. Disconnection forced"
03106, 00000, "fatal two-task communication protocol error"
03113, 00000, "end-of-file on communication channel"
03114, 00000, "not connected to ORACLE"
12570, 00000, "TNS: packet writer failure"
12571, 00000, "TNS: packet writer failure"
Specifies the connection to an Oracle database.
| Category | Value |
|---|---|
| Syntax | PlsqlDatabaseConnectString
If the format argument is not specified, then It is recommended that newer DADs do not use the |
| Default | None |
| Example |
|
If the database is running in the same Oracle home, or the environment variable "TWO_TASK" is set , this parameter need not be specified.
If the database is running in a separate Oracle home, then this parameter is mandatory.
If you have problems connecting to the database:
Check the username and password information in the DAD.
Make sure that you run "tnsping <string>" and execute commands such as:
sqlplus DADUsername/DADPassword@<string>
Ensure that TNS_ADMIN is configured properly.
Verify that the HOST:PORT:SERVICE_NAME format makes the connection go through.
Ensure that the TNS listener and database are up and running.
Ensure that you can ping the host from this machine.
From a mod_plsql perspective, TNSFormat and NetServiceNameFormat are synonymous and denote connect descriptors that are resolved by Net. The TNSFormat is provided as a convenience so that end-users use this to signify that the name resolution happens through the local tnsnames.ora. For situations where the resolution is through an LDAP lookup as configured in sqlnet.ora, it is recommended that the format specifier of NetServiceNameFormat be used.
If your database supports high availability, for example, RAC database, it is highly recommended that you use the NetServiceNameFormat such that the resolution for the net service name is through LDAP. This enables you to add or remove RAC nodes accessible through mod_plsql by just changing Oracle Internet Directory with the new/deleted node information. In such situations, hard-coding database listener HOST:PORT information in dads.conf or in the local tnsnames.ora is not recommended.
In older versions of the product, this configuration parameter was called connect_string.
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.
The following are the steps to obfuscate DAD passwords:
If necessary, switch user to the Oracle software owner user, typically oracle using the following command:
$su - oracle
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. |
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 |
|
|
HP-UX |
|
|
Linux, Solaris, and Tru64 UNIX |
|
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%
Change directory to the mod_plsql configuration directory for the current release of Oracle HTTP Server:
cd $ORACLE_HOME/Apache/modplsql/conf
Invoke the following Perl script to obfuscate DAD password:
perl dadTool.pl -o
Notes:
This is a mandatory parameter, except for a DAD that sets PlsqlAuthenticationMode to Basic and uses dynamic authentication.
For DADs using SingleSignOn authentication, this parameter is the name of the schema owner.
In older versions of the product, this configuration parameter was called password.
Specifies the username to use to logon to the database.
| Category | Value |
|---|---|
| Syntax | PlsqlDatabaseUsername string
|
| Default | None |
| Example | PlsqlDatabaseUsername scott
|
This is a mandatory parameter, except for a DAD that sets PlsqlAuthenticationMode to Basic and uses dynamic authentication.
For DADs using SingleSignOn authentication, this parameter is the name of the schema owner.
In older versions of the product, this configuration parameter was called username.
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
|
You can also use Oracle HTTP Server Rewrite rules to achieve the same effect as you get by setting this configuration parameter.
In older versions of the product, this parameter was called default_page.
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
|
Omit this parameter for applications that do not perform document uploads or downloads.
In older versions of the product, this parameter was called document_path.
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
|
Omit this parameter for applications that do not perform document uploads or downloads.
In older versions of the product, this parameter was called document_proc.
Specifies the table in the database to which all documents are uploaded.
| Category | Value |
|---|---|
| Syntax | PlsqlDocumentTablename string
|
| Default | None |
| Example | PlsqlDocumentTablename myschema.document_table
|
Omit this parameter for applications that do not perform document uploads or downloads.
In older versions of the product, this parameter was called document_table.
Specifies the Error Reporting Mode for mod_plsql errors. This parameter accepts the following values:
ApacheStyle: This is the default mode. In this mode, mod_plsql indicates to Oracle HTTP Server the HTTP error that was encountered. Oracle HTTP Server then generates the error page. This can be used with the Oracle HTTP Server ErrorDocument directive to produce customized error messages.
ModplsqlStyle: mod_plsql generates the error pages, usually a short message indicating the PL/SQL error that was encountered and PL/SQL exception stack, if any. For example:
scott.foo PROCEDURE NOT FOUND
DebugStyle: This mode provides more details than ModplsqlStyle. mod_plsql provides more details about the URL, parameters and also produces server configuration information. This mode is for debugging purposes only. Do not use this in a production system, since displaying internal server variables could be a security risk.
| Category | Value |
|---|---|
| Syntax | PlsqlErrorStyle ApacheStyle/ModplsqlStyle/DebugStyle
|
| Default | ApacheStyle
|
| Example | PlsqlErrorStyle ModplsqlStyle
|
In older versions of the product, this parameter was called error_style.
Specifies a pattern for procedures, packages, or schema names which are forbidden to be directly executed from a browser. This is a multi-line directive in which each pattern is on one line. The pattern is case-insensitive and can accept a wildcard such as '*'. The default patterns disallowed from direct URL access are: sys.*, dbms_*, utl_*, owa_*, owa.*, htp.*, htf.*, wpg_docload.*.
Setting this directive to "#NONE#" will disable all protection. This is not recommended for a live site and should not be done (This is sometimes used for debugging purposes).
If this parameter is overridden, the defaults still apply, which means that you do not have to explicitly add the default list to the list of excluded patterns.
| Category | Value |
|---|---|
| Syntax | PlsqlExclusionList [string/"#NONE#" multiline]
|
| Default | sys.*
|
| Example | PlsqlExclusionList myschema.private1.*
will disallow access to URLs which contain one of:
|
Besides the patterns specified with this parameter, mod_plsql also disallows any procedure name which contains special characters like tabs, newlines, carriage-returns, single-quotes, the reverse slash, the form feed, the open parenthesis, close parenthesis, and space. This cannot be changed.
In older versions of the product, this parameter was called exclusion_list.
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
|
This parameter is changed only for performance reasons. The minimum value for this parameter is 28, but it is seldom reduced.
Change this parameter only under the following circumstances:
The average response page is large and you want to reduce the number of round-trips mod_plsql makes to the database to fetch the response.
The character set in use is multi-byte, and you want to compensate for the problem of get_page or get_page_raw fetching fewer bytes for each row (calculations in the PL/SQL Web ToolKit are character-based and in the case of multi-byte characters, OWA packages assume a worst-case character byte size and do not attempt to pack each row to its maximum).
In older versions of the product, this parameter was called response_array_size.
In older versions of the product, the default for this parameter was 128.
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.
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
|
This parameter helps relieve memory and resource problems that may occur due to prolonged session reuse by a PL/SQL application.
This parameter should not need to be changed; the default is sufficient in most cases.
Setting this parameter to a low number can degrade performance. A case for a lower value might be an infrequently used DAD whose performance is not a concern, and for which limiting the number of requests provides some benefit.
In older versions of the product, the equivalent to this parameter is reuse. Instead of taking a value of "Yes" or "No", the new parameter enables you to have finer control over the connection pool reuse in mod_plsql.
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
|
Most applications have PlsqlTransferMode set to CHAR which means that the character set in PlsqlNLSLanguage needs to match the character set of the database. In one special case, where the database and mod_plsql are both using fixed-size character sets, and the character set width matches, the character set can be different. The response character set is always the mod_plsql character set.
If PlsqlTransferMode is set to RAW, then this parameter can be ignored.
In older versions of the product, this parameter was called nls_lang.
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
|
For applications that do not use path aliasing, this parameter may be omitted.
|
See Also: Oracle Application Server mod_plsql User's Guide for more information about path aliasing functionality. |
In older versions of the product, this parameter was called pathalias.
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
|
For applications that do not use path aliasing, this parameter may be omitted.
|
See Also: Oracle Application Server mod_plsql User's Guide for more information about path aliasing functionality. |
In older versions of the product, this parameter was called pathaliasproc.
PlsqlRequestValidationFunction
Specifies an application-defined PL/SQL function which gives you the opportunity to allow/disallow further processing of the requested procedure. This is useful in implementing tight security for your PL/SQL application by blocking out package/procedure calls which should not be allowed to execute from this DAD.
The function defined by this parameter must have the following prototype:
boolean function_name (procedure_name IN varchar 2)
Upon invocation, the argument 'procedure_name' will contain the name of the procedure that the request is trying to execute.
For example, if all the PL/SQL application procedures callable from a browser are inside the package "mypkg", then a simple implementation of this function can be as follows:
boolean my_validation_check (procedure_name varchar 2
is
begin
if (upper (procedure_name) like upper ('myschema.mypkg%')) then
return TRUE
else
return FALSE
end if;
end;
| Category | Value |
|---|---|
| Syntax | PlsqlRequestValidationFunction [string]
|
| Default | none |
| Example | PlsqlRequestValidationFunction myschema.mypkg.my_validation_check
|
By default, mod_plsql already disallows direct URL access to certain schemas/packages. For more information, refer to PlsqlExclusionList.
It is highly recommended that you provide an implementation for this function such that it only allows requests that belong to your application, and are callable from a browser.
Since this function will be called for every request, be sure to make this function as performant as possible. Suggested recommendations are:
Name your PL/SQL packages in a fashion such that the implementation of this function can be similar to the preceding example.
If your implementation performs a table lookup to determine what packages/procedures should be allowed, performance can be improved if you pin the cursor in the shared pool.
Specifies the cookie name when PlsqlAuthenticationMode is set to SingleSignOn. This parameter is supported only for Oracle Application Server releases, and is used by the OracleAS Portal and OracleAS Single Sign-On.
| Category | Value |
|---|---|
| Syntax | PlsqlSessionCookieName cookie_name
|
| Default | Same as DAD name |
| Example | PlsqlSessionCookieName mycookie
|
For DADs not using SingleSignOn authentication, this parameter can be omitted. In most other cases, the session cookie name should be omitted (and this parameter automatically defaults to the DAD name).
A session cookie name must be specified only for OracleAS Portal instances that need to participate in a distributed OracleAS Portal environment. For those OracleAS Portal nodes you want to seamlessly participate as a federated cluster, ensure that the session cookie name for all of the participating nodes is the same.
Independent OracleAS Portal nodes need to use distinct session cookie names.
In older versions of the product, this configuration parameter was called sncookiename.
Specifies how package and session state should be cleaned up at the end of each mod_plsql request.
Setting this parameter to StatelessWithResetPackageState causes mod_plsql to call dbms_session.reset_package_state at the end of each mod_plsql request.
Setting this parameter to StatelessWithPreservePackageState causes mod_plsql to call htp.init at the end of each mod_plsql request. This cleans up the state of session variables in the PL/SQL Web ToolKit. The PL/SQL application is responsible for cleaning up its own session state. Failure to do so causes erratic behavior, in which a request starts recognizing or manipulating state modified in previous requests.
Setting this parameter to StatelessWithFastResetPackageState causes mod_plsql to call dbms_session.modify_package_state(dbms_session.reinitialize) at the end of each mod_plsql request. This API is a lot faster than the mode of StatelessWithResetPackageState, and avoids some latch contention issues, but exists only in database versions 8.1.7.2 and higher. This mode uses up slightly more memory than the default mode.
| Category | Value |
|---|---|
| Syntax | PlsqlSessionStateManagement
|
| Default | StatelessWithResetPackageState
|
| Example | PlsqlSessionStateManagement
|
In older versions of the product, this configuration parameter was called stateful.
An older value of stateful=no or stateful=STATELESS_RESET corresponds to PlsqlSessionStateManagement StatelessWithResetPackageState
An older value of stateful=STATELESS_FAST_RESET corresponds to PlsqlSessionStateManagement StatelessWithFastResetPackageState
An older value of stateful=STATELESS_PRESERVE corresponds to PlsqlSessionStateManagement StatelessWithPreservePackageState
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.
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
|
This parameter only needs to be changed to enable sending back responses in different character sets from the same DAD. In such a case, the CHAR mode is useless, since it always converts the response data from the database character set to the mod_plsql character set.
In older versions of the product, RAW transfer mode was not supported.
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
|
For applications that do not do document uploads or downloads, this parameter may be omitted.
|
See Also: Oracle Application Server mod_plsql User's Guide for more information about upload and download processes and the structure of the restrictions on the document table format. |
In older versions of the product, this parameter was called upload_as_log_raw.
cache.conf file contains the cache settings for mod_plsql. This file contains parameters which specify the characteristics of the mod_plsql cache system.
|
Note: This file is relevant only if the PL/SQL Application uses theOWA_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:
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.
To define daily frequency, the keyword "Everyday" is used. The cleanup starts everyday at the time defined. For example, Everyday 2:00. This causes the cleanup to happen everyday at 2 AM (local time) in the morning.
To define weekly frequency, the days of the week such as "Sunday", "Monday", "Tuesday", and so on are used. For example, Wednesday 15:30. This causes the cleanup to happen every Wednesday at 3:30 PM (local time) in the afternoon.
To define monthly frequency, the keyword "Everymonth" is used. The cleanup starts at the Saturday of the month at the time defined. For example, Everymonth 23:00. This causes the cleanup to happen the first Saturday of every month at 11:00 PM (local time) at night.
| Category | Value |
|---|---|
| Syntax | PlsqlCacheCleanupTime <Sunday-Saturday, Everyday, Everymonth> <hh:mm>
|
| Default | Saturday 23:00 |
| Example | PlsqlCacheCleanupTime Saturday 23:00
|
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.
Enables mod_plsql caching.
| Category | Value |
|---|---|
| Syntax | PlsqlCacheEnable On/Off
|
| Default | Off |
| Example | PlsqlCacheEnable On
|
If you are sure that your application does not make use of the OWA_CACHE packages, in the PL/SQL Web Toolkit, then you can choose to disable caching. In such situations, there will be a very minor performance benefit.
In older versions, this parameter is called "enabled" and resided in the "[PLSQL Cache]" section of ORACLE_HOME/Apache/modplsql/cfg/cache.cfg.
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
|
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.
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;
1 megabytes = 1048576 bytes
10 megabytes = 10485760 bytes
| Category | Value |
|---|---|
| Syntax | PlsqlCacheTotalSize <number>
|
| Default | 20971520 (20 MB) |
| Example | PlsqlCacheTotalSize 20971520
|
In older versions, this parameter was called "total_size" and resided in the "[PLSQL Cache]" section of ORACLE_HOME/Apache/modplsql/cfg/cache/cfg.
This module provides proxy capability for FTP, CONNECT (for SSL), HTTP/0.9, HTTP/1.0, and HTTP/1.1.
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 subsequent sections:
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 precedingexample, you should use this replacement:
RewriteRule ^/+somepath(.*) /otherpath$1 [R]
This section discusses the following mod_rewrite directives:
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.
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.
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.
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.
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-10 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-10, a request to /xyz/oldstuff.html gets correctly rewritten to the physical file /abc/def/newstff.html.
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, al 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 |
|---|---|
|
|
|
|
|
|
|
|
|
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/.
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]
Increases Web application security by protecting Web application from known and unknown attacks.
