8 Oracle HTTP Server Modules

LoadModule

Loads the mod_oc4j module.

Oc4jCacheSize

Specifies the size of the OC4J connection cache.

Oc4jConnTimeout

Defines maximum idle time (in seconds) for unused connections.

Oc4jCookieExtension

Directs mod_oc4j to use JSESSIONID_<cookie_name_extension> as OC4J's session identifier in the cookie.

Oc4jExtractSSL

Governs passing SSL environment variables.

Oc4jEnvVar

Directs mod_oc4j to pass some environment variables from Oracle HTTP Server to OC4J.

Oc4jMount

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.

Oc4jMountCopy

Copies mount points from the base server.

Oc4jEnableSSL

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

Oc4jSSLWalletFile

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.

Oc4jSSLWalletPassword

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.

Process Management

With ApJServManual off, only one JServ engine can be started and managed automatically. Additional servlet engines have to be manually started, monitored and stopped.

With ApJServManual auto, any number of JServ engines can be started automatically. The process manager continually monitors the health of these processes and kills and restarts them, if necessary. You can still start JServ processes manually, if you need to.

Configuration

Configuring multiple JServ processes with ApJServManual on/ApJServManual off is more complicated and error prone. For example, a 10 process "balance" configuration requires thirty two directives and ten jserv.properties files.

Configuring multiple JServ processes with the new `auto' mode requires much less effort. For example, a ten process "balance" configuration requires only 3 directives.

ApJServManual

This directive accepts a mode, auto, which invokes the infrastructure functionality (in which mod_oprocmgr manages processes). The syntax is:

ApJServManual auto 

You can set the mode to "On" or "Off" to use the standard JServ functionality.

ApJServGroup

This directive defines groups for the process manager to manage for mod_jserv. If you have worked with mod_jserv, you will note that this directive replaces the ApJServBalance, ApJServHost, ApJServRoute and ApJServShmFile directives.

All JServ processes to be managed must belong to a group, and each group has its own ApJServGroup directive. If you only have one JServ process, you must define a group with just that process in it. The processes in a group are identical except for their listening ports, so requests directed to the group are distributed evenly among the processes.

The ApJServGroup directive takes four arguments: groupname, number of processes, node weight, and properties file. In the example below, the groupname is mygroup, the number of processes is 1, the node weight is 1, and the full path of the properties file used to start the JServ processes is ORACLE_HOME/Apache/JServ/etc/jserv.properties.

ApJServGroup mygroup 1 1 /private2/up_1022/Apache/Jserv/etc/jserv.properties

ApJServGroupMount

This directive defines a mount point and maps it to a process group and zone. In the example below, the mount point is /servlets, the group is mygroup, and the zone is root. Note that the balance protocol is in use for routing, as in the standard JServ configuration.

ApJServGroupMount /servlets balance://mygroup/root 

Place this directive after the ApJServGroup directive in the configuration file.

ApJServGroupSecretKey

This directive specifies the secret key that JServ needs to authenticate clients. It can be disabled, as shown below:

ApJServGroupSecretKey disabled

When activated, the directive takes one or two arguments. In the example below, with group and filename arguments, the filename mysecretkey applies to the group mygroup.

ApJServGroupSecretKey mygroup /usr/local/apache/jserv/mysecretkey

You can supply only the filename argument, as shown below. No group is named, so the secret key filename applies to all groups.

ApJServGroupSecretKey /usr/local/apache/jserv/mysecretkey

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

Place this directive after the ApJServGroup directive in the configuration file.

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.

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

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

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

• PlsqlAlwaysDescribeProcedure

• PlsqlAuthenticationMode

• PlsqlBeforeProcedure

• PlsqlBindBucketLengths

• PlsqlBindBucketWidths

• PlsqlCGIEnvironmentList

• PlsqlCompatibilityMode

• PlsqlDatabaseConnectString

• PlsqlDatabasePassword

• PlsqlDatabaseUserName

• PlsqlDefaultPage

• PlsqlDocumentPath

• PlsqlDocumentProcedure

• PlsqlDocumentTablename

• PlsqlErrorStyle

• PlsqlExclusionList

• PlsqlFetchBufferSize

• PlsqlInfoLogging

• PlsqlMaxRequestsPerSession

• PlsqlNLSLanguage

• PlsqlPathAlias

• PlsqlPathAliasProcedure

• PlsqlSessionCookieName

• PlsqlSesssionStateManagement

• PlsqlTransferMode

• PlsqlUploadAsLongRaw

Notes:

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

Notes:

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

Notes:

• 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 Oracle Application Server Portal and Oracle Application Server 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 through mod_plsql" chapter in the Oracle Application Server 10g mod_plsql User’s Guide for more information regarding different authentication modes.

  
  

Notes:

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

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.

Notes:

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

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.

Notes:

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

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.

Notes:

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

Notes:

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

Notes:

• If the database is running in the same Oracle home, or the environment variable "TWO_TASK" is set (called "LOCAL" on Windows NT), 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.

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 8-5 shows the appropriate environment variable for each platform.

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%
  
  

1. Change directory to the mod_plsql configuration directory for the current release of Oracle HTTP Server:

   cd $ORACLE_HOME/Apache/modplsql/conf
   
   

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

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

Notes:

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

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

Notes:

• Omit this parameter for applications that do not perform document uploads or downloads.

  
  

  See Also: Oracle Application Server 10g mod_plsql User’s Guide

  
  

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

Notes:

• Omit this parameter for applications that do not perform document uploads or downloads.

  
  

  See Also: Oracle Application Server 10g mod_plsql User’s Guide

  
  

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

Notes:

• Omit this parameter for applications that do not perform document uploads or downloads.

  
  

  See Also: Oracle Application Server 10g mod_plsql User’s Guide

  
  

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

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

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.

Notes:

• Besides the patterns specified with this parameter, mod_plsql also disallows any fully qualified procedure names which contain 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.

• To add a pattern to the defaults, you must specify the default list with the pattern you have added (as in the example in the table).

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

  
  

  See Also: Oracle Application Server 10g mod_plsql User’s Guide for more information regarding security.

  
  

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.

Notes:

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

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.

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

Notes:

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

Notes:

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

Notes:

• For applications that do not use path aliasing, this parameter may be omitted.

  
  

  See Also: Oracle Application Server 10g mod_plsql User’s Guide for more information about path aliasing functionality.

  
  

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

Notes:

• For applications that do not use path aliasing, this parameter may be omitted.

  
  

  See Also: Oracle Application Server 10g mod_plsql User’s Guide for more information about path aliasing functionality.

  
  

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

Notes:

• 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 Oracle Application Server Portal instances that need to participate in a distributed Oracle Application Server Portal environment. For those Oracle Application Server 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 Oracle Application Server Portal nodes need to use distinct session cookie names.

• In older versions of the product, this configuration parameter was called sncookiename.

• 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 OWA 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 StatelessWithResetPackageState/StatelessWithFastResetPackageState/StatelessWithPreservePackageState
  Default	StatelessWithResetPackageState
  Example	PlsqlSessionStateManagement StatelessWithResetPackageState

  
  

Notes:

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

Notes:

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

Notes:

• For applications that do not do document uploads or downloads, this parameter may be omitted.

  
  

  See Also: Oracle Application Server 10g 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.