Release 1 (9.0.1)
Part Number A90213-02
 Home |
 Book List |
 Contents |
 Index |  Master Index |  Feedback |
| 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_ose configuration file. See "Including Configuration Files in httpds.conf" for specific information.
mod_ose configuration file for your application. For the test application described in this chapter, the file is shown in "Example ose.conf".
The 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:
LoadModule ose_module /private1/Apache/modose/bin/libjipa9i.so
Once 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 httpd processes.
See "ose.conf" for more information about the LoadModule directive.
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: httpds.conf and ose.conf.
The main Apache configuration file used by the Oracle HTTP Server is httpds.conf. Where $APACHE_HOME is the Oracle HTTP Server home directory, this file is located in
$APACHE_HOME/Apache/conf/
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 include directive.
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
% $APACHE_HOME/bin/httpdsctl graceful
In the httpds.conf file, you need to modify or verify the following for mod_ose support.
Include directive that directly or indirectly includes the mod_ose configuration file ose.conf.
The configuration file for mod_ose is 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.
The ose.conf file contains standard Apache directives, such as IfModule, LoadModule, and Location. The structure of ose.conf is the following:
|
|
The |
|
|
The IfModule directive includes the directives following if the module source has been compiled into Apache. The directive is |
|
|
The
is a complete |
|
|
Terminates the |
The mod_ose-specific directives are:
These 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_plsql and mod_ose. Include the ose.conf file in this file, using an absolute file path, then make sure that the Apache main configuration file httpds.conf includes oracle_apache.conf.
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 Include for 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 httpds.conf file.
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 Include directive.
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.ora file located in the directory pointed to by the environment variable TNS_ADMIN, or
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".
The ose.conf file contains Apache configuration commands and directives, such as LoadModule, <IfModule>, and <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:
inst1_http =
(DESCRIPTION=
(ADDRESS=
(PROTOCOL=tcp)(HOST=sales-server)(PORT=1521)
)
(CONNECT_DATA=
(SERVICE_NAME=sales.us.acme.com)
(SERVER=shared)
(PRESENTATION=http://sales)
)
)
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_ose
mod_ose should connect to
addendpoint command, 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.
The 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":
dispatchers="(PROTOCOL=tcp)(SERVICE_NAME=MODOSE)"
dispatchers="(PROTOCOL=tcps)(SERVICE_NAME=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=
(ADDRESS=(PROTOCOL=tcp)(HOST=server27)(PORT=5521))
(CONNECT_DATA=
(SERVICE_NAME=MODOSE)
(SERVER=shared)
(PRESENTATION=http://admin)
)
)
You will now have a shared dispatcher and server that will not be used by other clients--only by mod_ose.
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.
Use the 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
exportwebdomain [options] /HRRoot
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:
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.conf file in the same directory as gencfg.pl and updates the AuroraService and AuroraWorkersPerProcess directives if they already exist.
exportwebdomain command. The arguments to the exportwebdomain command are constructed by the Perl script, based on the data either in the input description file webdata.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 webdata.cfg are:
|
type |
Optional key. If the value is simple, use the simple mode. If this key is not provided, use the exportwebdomain mode. |
|
netservice |
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. |
|
worker |
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. |
|
domains |
Web domain for which the configuration is to be generated. Mandatory if type is exportwebdomain. |
|
context |
Optional key. The servlet context to be used for Web domain. If not provided, configuration is generated for all the contexts in that domain. |
|
alias |
The database to which the session shell should connect. Optional--if not supplied, uses the local database |
|
nodocs |
Optional key. If true, do not generate configuration for documents. |
|
nodefault |
Optional key. If true, do not generate configuration for default servlets. |
An example of key:value pairs in a description file (webdata.cfg) is
netservice:inst1_http nodocs:true nodefault:true workers:1 context:admin domains:/system/admin
When 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:
config object for the servlet context (in the OSE server's JNDI namespace), add a group entry called context.properties.
context.locationservice property in this group to the connect identifier for the desired service, as specified in the tnsnames.ora listener initialization file. Use the session shell addgroupentry command to do this. For example, in the session shell, do
$ cd /system/admin/contexts/default $ addgroupentry config context.properties context.locationservice
inst2_https $ cd /HRRoot/contexts/HRService $ addgroupentry config context.properties context.locationservice inst3_http
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>
|
Note:
The locations specified in the |
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 configuration file
tnsnames.ora, with the TCPS protocol and a TCPS listener port. For example:
inst1_https = (DESCRIPTION=
(ADDRESS=(PROTOCOL=tcps)(HOST=server27)(PORT=5524))
(CONNECT_DATA=
(SERVICE_NAME=rdbms817.rdbms.dev.us.oracle.com)
(SERVER=shared)
(PRESENTATION=http://admin)
)
)
Oracle Net uses the service name rather than the SID that was used in earlier versions of the Oracle server.
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.
Before chaining mod_osso with 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.
To use 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:
<Location /<context_virtual_path>/<servlet_virtual_path/>
AuthName "OSSO Server on machine1"
AuthType Basic
require valid-user
</Location>
Enter this 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:
<Location /<context_virtual_path>/<servlet_virtual_path/>
SetHandler aurora-server
</Location>
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 httpds.conf.
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 realm publish command with the -type OSSO option, as shown in the following example:
$ realm publish -w[ebservice] <serviceRoot> -type OSSO
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:
$ realm publish -w[ebservice] <webserviceRoot> -remove ossoRealm
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:
$ realm secure -s /testRoot/contexts/mycontext -osso
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 httpSecurity servlet.
A standard 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
$ getproperties /testRoot/contexts/mycontext/httpSecurity
This returns:
servlet.class=SYS:oracle.aurora.mts.http.security.OSSOSecurity
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.
|
Note:
For the |
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.
AuroraService directive in the ose.conf file specifies the correct entry in the tnsnames.ora file, 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 tnsnames.ora entry.
lsnrctl command.
lsnrctl status command to view the status of each listener port.
ps -e under UNIX, or the TaskManager under Windows NT), should show one or more httpds processes running.
httpds.conf and ose.conf files have been read by Apache.
doc_root specified for that service and context is valid
|
 Copyright © 1996-2001, Oracle Corporation. All Rights Reserved. |
|