|Oracle9i Servlet Engine Developer's Guide
Release 1 (9.0.1)
Part Number A90213-02
This chapter describes how to configure the Oracle HTTP Server (powered by Apache) and the Apache
mod_ose module that is used to connect to the Oracle Servlet Engine (OSE/OJVM).
This chapter contains the following topics:
To set up the Oracle HTTP Server and the
mod_ose module that is used to connect Apache to the Oracle Servlet Engine (OSE/OJVM), you need to take the following steps:
The OSE/OJVM requires an Oracle Shared Server configuration. If you do not normally have or use this configuration, see "Non-Shared Server Installations" for a workaround.
DBSession, which is a stateful servlet. See "Examples" for the instructions on coding and installing this servlet.
mod_ose. See "tnsnames.ora" for specific information.
mod_oseconfiguration file. See "Including Configuration Files in httpds.conf" for specific information.
mod_oseconfiguration file for your application. For the test application described in this chapter, the file is shown in "Example ose.conf".
mod_ose module is configured into Apache by including its configuration file in the main Apache configuration file. In the
mod_ose configuration file, the first line (apart from any comments) points to the location of the dynamic library that implements
mod_ose, using the
LoadModule directive. For example:
mod_ose module is part of Apache, each daemon Apache process (
httpd process) that the Apache listener starts includes
mod_ose. There is no need to specifically start
mod_ose. This is the normal way that Apache modules are included in the
See "ose.conf" for more information about the
When an Apache process starts up, it reads the Apache configuration file to determine how it should run. The Apache configuration file, and additional configuration files that it includes, determine which modules are included in Apache, and thus how HTTP requests are handled: whether they are handled directly by Apache, or routed to the servlet engine for handling there.
There are two configuration files that you must set up to get Apache and
mod_ose running properly:
The main Apache configuration file used by the Oracle HTTP Server is
$APACHE_HOME is the Oracle HTTP Server home directory, this file is located in
This is the only file that Apache reads directly when it starts up. Other configuration files are read when they are included in
httpds.conf, using the
Configuring Apache and
mod_ose is not dynamic. When you change a configuration file, you must restart Apache. However under Solaris there is a way to restart Apache on the fly, so that the configuration files are read but active connections are still maintained. Use the OS command
httpds.conf file, you need to modify or verify the following for
Includedirective that directly or indirectly includes the
The configuration file for
ose.conf. It is located in
$APACHE_HOME/modose/conf/. This file determines which Oracle listener connections are supported, and how requests to OSE are routed through the Oracle listener to the appropriate Web service, servlet context, and servlet.
ose.conf file contains standard Apache directives, such as
Location. The structure of
ose.conf is the following:
The IfModule directive includes the directives following if the module source has been compiled into Apache. The directive is
is a complete
mod_ose-specific directives are:
Mandatory directive that specifies the connect identifier (in the listener initialization file
This directive is not meaningful for current Solaris releases of the Oracle HTTP Server, as Solaris Apache is single-threaded. On Windows NT, each Apache process can execute more than one client request at a time.
Optional directive included in the
mod_ose-specific directives are generated in the configuration file using the session shell
exportwebdomain command, or using the
gencfg.pl Perl program.
Here is an example of an ose.conf file:
LoadModule ose_module /private1/Apache/modose/bin/libjipa9i.so # # Apache configuration # Domain: /system/admin # Context: admin # <IfModule mod_ose.c> AuroraService inst1_modosetest AuroraWorkersPerProcess 1 # # Context for VPATH /admin/ # <Location /admin/deploywar > SetHandler aurora-server </Location> <Location /admin/error_log_viewer.htm > SetHandler aurora-server </Location> <Location /admin/errors/internal > SetHandler aurora-server </Location> <Location /admin/event_log_viewer.htm > SetHandler aurora-server </Location> <Location /admin/http_log_viewer.htm > SetHandler aurora-server </Location> <Location /admin/shell > SetHandler aurora-server </Location> <Location /ose/ > SetHandler aurora-server </Location> <Location /test/ > SetHandler aurora-server </Location> </IfModule> # # End of configuration #
Contains includes for Oracle-specific modules, such as
mod_ose. Include the
ose.conf file in this file, using an absolute file path, then make sure that the Apache main configuration file
You can include the
mod_ose configuration file
ose.conf in the Apache configuration file
httpds.conf directly, using the Apache
Include directive. However, Oracle recommends that you add the
ose.conf to the configuration file
oracle_apache.conf, which also includes the configuration files for other Oracle-specific Apache modules such as
mod_plsql ($APACHE_HOME/modplsql/conf/plsql.conf). The
oracle_apache.conf file is located in
$APACHE_HOME/Apache/conf/. Then include
oracle_apache.conf in the
Always specify the files to be included using absolute paths to the files, as Apache cannot recognize relative paths. Also, do not use operating system environment variables, such as the UNIX shell variable
$APACHE_HOME, or the Windows NT environment variable
%APACHE_HOME% in the
Connections from Apache/
mod_ose to the OSE use the Oracle Net protocol, the same as OCI or Forms client/server applications.
mod_ose uses the same mechanism for finding connection descriptors as other Oracle clients, such as OCI clients. Depending on the configuration determined by the
sqlnet.ora file, connections are defined either by
tnsnames.orafile located in the directory pointed to by the environment variable TNS
See the Oracle Net Administration Guide for more information about configuration of listeners and dispatchers for the Oracle server.
So to use
mod_ose with the OSE/OJVM you must at least configure the Oracle listener's initialization file:
tnsnames.ora, to include connect descriptors for the connections to the OSE server. You can find specific information about doing this in "tnsnames.ora".
ose.conf file contains Apache configuration commands and directives, such as
<Location>. To create a configuration file, you could analyze your application, find the servlet contexts that
mod_ose must recognize and transfer HTTP requests to, and create the
mod_ose configuration file by hand, using a text editor. Or you could modify the example files that are supplied with Oracle.
These approaches, however, are very error-prone, and are not recommended.
Oracle recommends that you create a
ose.conf file using the tools supplied to generate this file. With Oracle8i, you used the
exportwebdomain session shell command to create the
mod_ose configuration for specific Web applications. With Oracle9i, you can still use the
exportwebdomain command, or you can use the new Perl script
gencfg.pl. This script takes a descriptor file as input, and generates or modifies a
mod_ose configuration file. This tool is described in "gencfg.pl".
This Oracle Net initialization file specifies the connect descriptors that are used by the Oracle listener. An example of this file is provided with all Oracle server installations, as well as with Oracle client-side installations. For a complete description of the entries in this file, see the Oracle Net Administrator's Guide. In some cases, you might have to copy the file from an example location before modifying it. For example, in an NT client configuration, copy the file from
%ORACLE_HOME%\network\Admin\Sample up to
%ORACLE_HOME%\network\Admin, and then modify it to add the
mod_ose-specific connect identifiers.
Modify this file to add one or more connect identifiers that point to OSE services. Here is an example of a possible entry:
In this example, the connect identifier
inst1_http is associated with a connect descriptor that specifies the TCP/IP protocol, a host named
sales-server, and a service that listens on the Net8 port 1521. A service name,
sales.us.acme.com is specified, and the presentation is HTTP. The service name is the instance name in the INIT.ORA file (there can be multiple instance names in the case of Oracle Real Application Cluster installations). You create the service (the presentation) using the
createwebservice session shell command.
The connect identifier
inst1_http is an arbitrary name. This connect identifier is generated into the
ose.conf file, in the
AuroraService directive, by the configuration utilities. For an example, see the section "gencfg.pl".
The address part of the connect descriptor specifies
mod_oseshould connect to
addendpointcommand, described in "addendpoint" and in the Oracle9i Java Tools Reference.
This part of the entry provides a service name, the kind of server (shared or dedicated), and the presentation. The presentation is the HTTP service that you established for your application.
mod_ose module requires a shared server installation to run. It will not run if the database is not configured with any shared dispatchers/servers. However, some users prefer not to run with shared servers as a standard configuration. Oracle recommends the following work around to let you use Apache and
mod_ose in a dedicated server environment.
In the database initialization file (
INIT.ORA), create one or more dedicated dispatchers and servers with a specific service name. You can use any service name that follows the
INIT.ORA conventions as long as it differs from the database service name. The following examples use "MODOSE":
The connect identifier in the tnsnames entry (
tnsnames.ora file) should use this service name rather than the database service name.
inst2_http = (DESCRIPTION=
You will now have a shared dispatcher and server that will not be used by other clients--only by
The Oracle9i servers support the two utilities for generating configuration files for
mod_ose. They are described in the following sections.
The configuration of Web applications running on OSE is specified in the JNDI namespace on the OSE server. The session shell command
exportwebdomain extracts the information about the applications installed in a Web domain and generates the corresponding configuration file.
exportwebdomain command to generate the structure of a Web domain in a configuration file for mod_ose. The export utility works in two stages:
mod_ose. Generates a configuration file at the shell level.
This session shell tool can be used to generate the
mod_ose configuration file.
exportwebdomain takes as an argument the name of the Web domain for which you want to generate a configuration. For example
generates a configuration file for the Web domain
HRRoot, which is located at the root of the JNDI namespace in the OSE server. The options to
exportwebdomain are the following:
Optional parameter that specifies the name of the servlet context to support. If not specified, all contexts in the domain are configured.
The name of the service defined in the
The XSLT transformation type. For example
Optional parameter that specifies the number of worker threads per Apache process. In the release, this option applies only to NT installations, since the current release of Solaris Apache is always single-threaded.
Optional parameter that indicates not to map the default context, unless indicated by the -
Optional parameter that specifies to not forward URLs mapped into
gencfg.pl is a Perl program that generates or modifies configuration files for
mod_ose based on an input description file. The description file contains key:value pairs in a text format. The output is generated in the file
ose.conf in the same directory. If the file already exists, new material is added to it.
The Perl script provides for two modes of configuration:
ose.conffile in the same directory as
gencfg.pland updates the
AuroraWorkersPerProcessdirectives if they already exist.
exportwebdomaincommand. The arguments to the
exportwebdomaincommand are constructed by the Perl script, based on the data either in the input description file web
data.cfg, or in another file specified in an argument on the command line. The session shell is then executed by the Perl program. The OSE database must be running when you use this mode.
The keys and possible values in
Optional key. If the value is simple, use the simple mode. If this key is not provided, use the exportwebdomain mode.
Mandatory key. The Oracle Net connect name to be used in generating the AuroraService directive in the output configuration file. See "ose.conf" for more about this directive.
Optional key. The number of worker threads to be used for each Apache process. Used only for NT Apache in this release. The default is 1 when not specified.
Web domain for which the configuration is to be generated. Mandatory if type is exportwebdomain.
Optional key. The servlet context to be used for Web domain. If not provided, configuration is generated for all the contexts in that domain.
The database to which the session shell should connect. Optional--if not supplied, uses the local database
Optional key. If true, do not generate configuration for documents.
Optional key. If true, do not generate configuration for default servlets.
An example of key:value pairs in a description file (
gencfg.pl is executed with this input file, it generates the following
ose.conf configuration file:
# # Apache configuration # Domain: /system/admin # Context: admin # <IfModule mod_ose.c> AuroraService inst1_http AuroraWorkersPerProcess 1 # # Context for VPATH /admin/ # <Location /admin/deploywar > SetHandler aurora-server </Location> <Location /admin/error_log_viewer.htm > SetHandler aurora-server </Location> <Location /admin/errors/internal > SetHandler aurora-server </Location> <Location /admin/event_log_viewer.htm > SetHandler aurora-server </Location>
Use this directive in the following way:
configobject for the servlet context (in the OSE server's JNDI namespace), add a group entry called
context.locationserviceproperty in this group to the connect identifier for the desired service, as specified in the
tnsnames.oralistener initialization file. Use the session shell
addgroupentrycommand to do this. For example, in the session shell, do
When you execute the
exportwebdomain session shell command to create a
mod_ose configuration file, either directly or by using the
gencfg.pl Perl program, the
Location directives for the configured locations will contain the
AuroraLocationService directive. For example
<Location /system/admin/contexts/default/ > AuroraLocationService inst2_https SetHandler aurora-server </Location> <Location /HRRoot/contexts/HRService/ > AuroraLocationService inst3_http SetHandler aurora-server </Location>
The locations specified in the
Even if you specify a stateless handler (
Specify whether a request uses the stateful or the stateless connection by indicating which Apache handler to use. You indicate the handlers in
Location directives in the
ose.conf configuration file. For example:
This handler specifies a stateless connection. If a servlet being served by a stateless connection attempts to create an
HttpSession object, it is considered an error.
This handler specifies a stateful connection. It allows a servlet to create an
HTTPSession object, and requires Apache to define a separate session to service the requests.
This specifies the default mode, which is stateful.
mod_ose can accommodate SSL connections between Apache and the OSE/OJVM, to support SSL connections between the client and OSE/OJVM. You need the following to set up SSL service:
tnsnames.ora, with the TCPS protocol and a TCPS listener port. For example:
Oracle Net uses the service name rather than the SID that was used in earlier versions of the Oracle server.
An ADDRESS_LIST (host, port, protocol) in the case of multiple Oracle Listeners on the back end (multiple nodes). This allows for load balancing and fail-over configurations, as well as the use of CMAN for connection concentration.
Read the Oracle Net Administrator's Guide for information about how to set this parameter.
group of database instances: specify SERVICE_NAME
single database instance: specify INSTANCE_NAME
See "Using mod_osso with mod_ose" for basic information about
mod_osso. This section tells you how to configure
mod_osso to work with the Oracle HTTP Server and
mod_ose, you must register the Oracle HTTP Server with an Oracle Single Sign-On server. See the documentation on the Oracle HTTP Server for more information.
mod_osso, just protect a virtual path with
mod_osso. To do this, define a
Location directive in the Apache configuration file
httpds.conf as follows:
AuthName "OSSO Server on machine1"
Location directive in the
<IfModule mod_osso.c> section of the Apache
httpds.conf configuration file. For more information about this, including other required options, see the Apache documentation, and the Oracle HTTP Server Administration Guide (available with Oracle9i Internet Application Server V2).
Next, configure a virtual path to be forwarded to the OSE/OJVM. For example, add the following
Location directive to the
ose.conf configuration file:
Enter this in the
<IfModule mod_ose.c> section of
ose.conf, and use the same virtual servlet context and virtual servlet path as in the
Location directive in the
mod_osso.c section of
Secure the virtual path in the OSE/OJVM with the OSSO authentication method by publishing a special OSSO realm for each Web service in the OSE/OJVM. If you plan to service requests which have been authenticated by an OSSO server, you must have an OSSO HTTP security realm published in each service root that is accessed by such a request.
Publish the special OSSO realm by using the session shell
publish command with the
-type OSSO option, as shown in the following example:
It is not necessary to specify the realm name in the
-add parameter. The realm with authentication type OSSO will always be called
ossoRealm. In fact, any other name you specify in the
-add parameter is ignored.
You can remove an OSSO realm just as any other realm. Use the session shell
realm publish command with the
-remove option, as shown in this example:
You can configure OSSO authentication at the level of servlet context. As with regular HTTP security, you use the session shell
realm secure command, as shown in this example:
Note the special
-osso flag. It tells the realm command that OSSO authentication should be enabled for this servlet context. The
realm secure command binds a JNDI object called
httpSecurity into the
/testRoot/contexts/mycontext. You can use the session shell
ls command to verify the existence of the
realm secure command, without the
-osso option, also binds an
httpSecurity object into the context. The difference is in the class bound to
httpSecurity. For a regular HTTP Security method,
httpSecurity is bound to a servlet of class
oracle.aurora.mts.http.security.HttpSecurity. In the case of OSSO authentication it is bound to
oracle.aurora.mts.http.security.OSSOSecurity. You can use the session shell
getproperties command to verify the class binding, as shown in
Servlet contexts are secured with the HTTP Security method by default when they are created. So if you need OSSO authentication, you must explicitly use the
realm secure command with the
-osso option to change the type of authentication to OSSO.
It is also possible to configure a servlet context for OSSO authentication when creating the servlet context using a WAR file. For more information about this, see "Authenticating with Oracle Single Sign-On".
If you have trouble connecting through
mod_ose to your servlets or JSPs running in the OSE/OJVM server, you can take the following steps to find the source of the problem.
AuroraServicedirective in the
ose.conffile specifies the correct entry in the
tnsnames.orafile, and that this entry has the correct service name, service type, protocol type, and port number. See "tnsnames.ora" for more information.
You can also use the
tnsping utility to test the
lsnrctl statuscommand to view the status of each listener port.
ps -eunder UNIX, or the TaskManager under Windows NT), should show one or more
ose.conffiles have been read by Apache.
doc_rootspecified for that service and context is valid