10g (9.0.4)
Part Number B10381-01
 Home |
 Solution Area |
 Contents |
 Index |
| Oracle HTTP Server Administrator's Guide 10g (9.0.4) Part Number B10381-01 |
|
This appendix explains how the Oracle Application Server Proxy Plug-in enables you to use components in conjunction with a third-party HTTP listener. The Oracle Application Server Proxy Plug-in works with the Sun ONE Web Server Enterprise Edition, version 4.1 and 6.0, on UNIX and Windows NT systems, or the Microsoft Internet Information Server (IIS), version 4.0 or 5.0 on Windows systems, to send requests to Oracle Application Server.
Topics discussed are:
Oracle Application Server Proxy Plug-in is a reverse HTTP proxy. The plug-in forwards incoming HTTP requests to an Oracle Application Server instance as shown in Figure A-1.
This proxy logic is provided as a plug-in, a shared library that is loaded by the third-party HTTP listeners. The plug-in uses APIs provided with the third-party listeners to directly handle HTTP requests, in much the same way that modules are plugged into Oracle HTTP Server.
Oracle HTTP Server can mimic the address and port that the third-party listener is using. That is, when sending a request to Oracle HTTP Server, the proxy can be configured to send a different Host: HTTP header than the actual hostname and port that the request is being sent to, so that downstream applications are shielded from the introduction of the reverse proxy.
The plug-in is distributed on the OracleAS Repository Creation Assistant/Utilities CD, which is included in your Oracle Application Server CD Pack.
After downloading the plug-in, place the configuration files and shared library in directories that the third-party listener can access.
The plug-in consists of a single shared library, oracle_proxy.so. To install the plug-in into the listener, place the library in a directory to which the listener has read and execute privileges.
The plug-in consists of a single .dll, oracle_proxy.dll for IIS, or oracle_proxy_nes.dll for Sun ONE. To install this plug-in, copy the .dll to a directory the listener can access.
When you install Oracle Application Server, you can administer Oracle HTTP Server using Application Server Control. However, if you choose to use Sun ONE or IIS instead of Oracle HTTP Server, then it is recommended that you disable Oracle HTTP Server on Application Server Control so that it no longer appears there.
Oracle does not support monitoring or administering of non-Oracle HTTP Server listener with Application Server Control.
|
See Also:
|
There is one configuration file for Oracle Application Server Proxy Plug-in. It controls the proxy functionality. The presence of the configuration file in the Web server's file system makes the functionality active.
You also need to modify configuration files specific to the third-party listener to enable the plug-in on to these listeners.
The proxy server definition file must reside in a directory that is readable by the third-party listener. For simplicity, you could create a directory called proxy in a convenient location on your system, and place the proxy server definition file, the proxy module file (oracle_proxy.dll for Windows NT IIS, oracle_proxy_nes.dll for NT Sun ONE, or oracle_proxy.so for Solaris Sun ONE), and proxy log files in it.
Described in detail in Proxy Configuration File Parameters section below, the proxy server definition file contains:
You can create this file with the text editor of your choice. The oproxy.serverlist parameter must list at least one server name, or the proxy will not function.
Example A-1 provides a sample proxy server definition file.
# This file defines proxy server behavior.
#
# Server names that the proxy plug-in will recognize.
oproxy.serverlist=ias1
# Hostname to use when communicating with a specific server.
oproxy.ias1.hostname=oasdocs.us.oracle.com
# Port to use when communicating with a specific server.
oproxy.ias1.port=7777
# Description of URL(s) that will be redirected to this server.
oproxy.ias1.urlrule=/*
The following section discusses the proxy configuration file parameters listed below:
Lists all of the server names that the plug-in recognizes.
Defines the hostname to use when communicating with a specific server.
| Category | Value |
|---|---|
|
Parameter Type |
string |
|
Allowable Values |
Valid hostname |
|
Default Value |
None. |
|
Example |
|
defines the port to use when communicating with a specific server.
| Category | Value |
|---|---|
|
Allowable Values |
Valid port value |
|
Default Value |
80. |
|
Example |
|
Supports the mimicing feature of the proxy by defining the hostname and port that clients use to access the third-party HTTP listener. If defined, this value will be passed as the Host: HTTP header. If not defined, the hostname and port of the machine actually being communicated with will be sent.
| Category | Value |
|---|---|
|
Parameter Type |
string |
|
Allowable Values |
host:port |
|
Default Value |
|
|
Example |
|
Describes a URL or set of URLs that are redirected to this server. A given server can have any number of urlrule properties assigned to it.
| Category | Value |
|---|---|
|
Parameter Type |
string |
|
Example |
oproxy.ias1.urlrule=/foo/* |
Three types of rules can be used: exact match, context match, or suffix match.
For example:
oproxy.ias1.urlrule=/foo/bar/foo.html would map only the URL /foo/bar/foo.html to be proxied to the server with the name ias1 (the details for the server ias1 are configured in the server configuration file).
oproxy.ias1.urlrule=/foo/* would map URLs beginning with /foo to the server with the name ias1.
For context matches, you can use the stripcontext option with the urlrule parameter to send only the portion of the url following the wildcard to the server. The default for the stripcontext option is false, so you do not need to include it unless you are setting it to true. It is shown below for completeness of the example.
Example: In following configuration:
oproxy.ias1.urlrule=/ias1/* oproxy.ias1.stripcontext=false
and the URL request:
http://hostname/ias1/header1.gif
retrieves
ORACLE_HOME/Apache/Apache/htdocs/ias1/header1.gif
In the following configuration:
oproxy.ias1.urlrule=/ias1/* oproxy.ias1.stripcontext=true
and the URL request:
http://hostname/ias1/header1.gif
retrieves
ORACLE_HOME/Apache/Apache/htdocs/header1.gif
For example, oproxy.ias1.urlrule=/*.jsp would map all of the URLs that end in .jsp to the server ias1. This can be combined with the context rule to have something like /foo/bar/*.jsp so that only URLs that start with /foo/bar and end in .jsp would be proxied.
In the proxy server definition file, you define which servers and URLs to proxy to the plug-in.
oproxy.serverlist=ias1,ias2
oproxy.ias1.hostname=myhost.us.oracle.com
oproxy.ias1.port=7777
oproxy.ias1.alias=www.oracle.com
The hostname must be provided. If you do not specify the port, 80 is assigned. If an alias value is not given, the combination of the hostname and port given are used. The alias enables the back end server to receive requests that have an HTTP Host: header that looks exactly like the one the client delivers to the third-party listener.
urlrule parameter to specify redirection between servers. For example, the rule:
oproxy.ias1.urlrule=/*
maps all incoming requests to be proxied to the Web server on the server ias1. These rules can be of three forms, exact URL, context match, or extension-based. An exact match maps exactly one URL to a server, for example:
oproxy.ias1.urlrule=/my/path/index.html
maps only accesses to /my/path/index.html for proxying. An example of a context rule is:
oproxy.ias1.urlrule=/app1/*
which maps any URL beginning with /app1. An extension-based rule, such as:
oproxy.ias1.urlrule=/*.jsp
maps any URL ending with .jsp.
All requests sent to a mapped URL are proxied through HTTP/1.1 to the specified server.
This section provides proxy plug-in configuration instructions for Sun ONE Enterprise Server listener on UNIX and Windows NT systems.
magnus.conf file in version 6, or obj.conf in version 4 in the Sun ONE listener /config directory.
On UNIX:
Init fn="load-modules" shlib="/path/oracle_proxy.so" funcs=op_init,op_ objecttype,op_service
On Windows:
Init fn="load-modules" shlib="/path/oracle_proxy_nes.dll" funcs=op_init,op_ objecttype,op_service
where /path/ is the path to the shared library for the plug-in. This line tells the listener where the proxy shared library is, and which functions are exposed by this library.
Init fn="op_init" server_defs="/path/servers" logfile="/path/oproxy.log" log_level=error
where /path/ is the path to the proxy server definition and log files. The proxy server definition file contains all of the configuration information for the servers that the proxy plug-in can communicate with. A log file and log level to log messages from the plug-in can also be specified (optional).
|
See Also:
"Proxy Server Definition File" for a complete description and example. |
<Object name=default> section of the obj.conf file, before all other lines beginning with the word ObjectType:
ObjectType fn=op_objecttype UseOutputStreamSize=8192
Service:
Service type="oracle/proxy" fn="op_service"
This section provides proxy plug-in configuration instructions for the IIS listener on Windows systems. The process involves creating Windows registry entries and using the IIS management console to add directories and filters. You must restart the listener after configuring the plug-in.
To configure the plug-in, follow the steps below:
regedit and click OK.
The Registry Editor window opens.
HKEY_LOCAL_MACHINE folder (click on the + preceding its name).
SOFTWARE folder (click on the + preceding its name).
ORACLE folder.
A new folder is added under the ORACLE folder with the name New Key #1.
IIS Proxy Adapter for the key name.
A new value is added in the right window pane with the name New Value #1.
server_defs for the value name.
log_file and log_level using the procedure specified in steps 8-11. This is optional.
oracle_proxy.dll. Name the directory oproxy and give it execute access.
oracle_proxy.dll as a filter in your IIS Web site. The name of the filter should be oproxy and its executable must point to the directory containing oracle_proxy.dll (for example, d:\proxy\oracle_proxy.dll).
osso filter is marked with a green upward arrow.
This section highlights development and usage practices to consider when developing an application that runs behind the Oracle Application Server Proxy Plug-in. Some of these also have relevance when enabling an application to run behind Oracle Application Server Web Cache.
This is usually only relevant if an application has a module that plugs directly into the Oracle HTTP Server. Specifically, look for dependencies on obtaining information about the client based on the connection made to the Oracle HTTP Server, such as using the SSL certificate for authentication. Currently, SSL is not supported, so even if the client uses SSL to connect to the third-party listener, an unencrypted HTTP message will be sent from the third-party listener to the Oracle HTTP Server. This means that client certificates will not be available to components that reside behind the plug-in. The environment variable REMOTE_ADDR has been specifically preserved when Oracle Application Server Proxy Plug-in and Oracle Application Server Web Cache are used, but other client information may, in practice, represent the machine on which the proxy resides rather than the actual client host. These behaviors must be discovered and eliminated in cases where the Oracle HTTP Server is not the external listener for Oracle Application Server.
This includes static HTML pages, dynamic pages generated by servlets, JSPs, PL/SQL, etc. Examine all code that obtains the server name of Oracle HTTP Server to ensure that it is not embedding the server name into pages that are sent back to the client. To test for this behavior, use a "spider" application that traverses all links in a Web site. Open source tools with this functionality are available.
If you have an application that uses browser-based code, ensure that the code does not contain the hostname and port of Oracle HTTP Server that actually delivers the content. Instead, it must have the actual client-accessible address used by the third-party listener.
In order to successfully proxy all requests for an application, the Oracle Application Server Proxy Plug-in must have a complete description of the URL space for that application. Each Oracle Application Server application must describe the set of rules necessary to configure the plug-in for that application. This set of rules must include all URLs that the application could generate. If an application generates a URL that is not described by the proxy urlrule parameters, the request will be served by the third-party HTTP listener, and a "document not found" error may occur (or, worse, a document other then the intended document may be delivered to the client).
Developers of applications that use common top level directories (such as a reliance on mapping /images) should be prepared to:
.gif and .jpg files anyway, but it requires extra effort.
This section describes common problems and possible solutions.
"Proxy Server Definition File" for a description of this file and parameter requirements.
See Also:
Init lines are added to the magnus.conf file and ObjectType and Service lines are added to the obj.conf file.
urlrule parameter is set up correctly, and consider whether the stripcontext option should be set to true.
serverlist line in the proxy server definition file specifies the back-end server you are trying to reach.
urlrule parameters in the proxy server definition file target the correct area on the back-end server.
Do not display an IIS pages with a Sun ONE browser.
If you try to change the ports or turn on security (for SSL), the server may return the error message "Unable to parse magnus.conf".
Remove any comments and added lines preceding and following the Init lines in the magnus.conf file.
If you are using a context-based urlrule parameter to retrieve a file that is known to exist, and the listener returns "Not Found", you probably need to set "stripcontext=true".
The IIS and Sun ONE servers auto-complete URLs differently. Requests of "http://serviceman", "http://serviceman/", and "http://serviceman/index.html" do not necessarily return the same results on different platforms. The oproxy.servername.urlrule parameter can be used to work around this problem.
The default Sun ONE configuration maps any URL requests to "/servlet" to its own servlet handler. You must edit the proxy server definition file, or change the Sun ONE configuration to correct this.
If you use an exact urlrule parameter, for example, "urlrule=/*.html", in the proxy server definition file (or a similar scenario), the server retrieves the specified page, but all other links are forbidden to the user, including inline images in the page. (If you use an exact urlrule with stripcontext=true, a "Server Error" is returned.)
Clear the memory cache in your client browser. Earlier versions of Sun ONE and IE cache pages even when told to retrieve the page every time, when no memory is allocated for caching (you may need to restart the browser to get this behavior to work). If you see a page you're not expecting, try refreshing or reloading the page.
The REMOTE_ADDR field usually contains the IP address of the client machine. In some URL request cases, if there is a proxy server in the environment, the field may contain the IP address of the proxy server.
If the back-end server returns a redirect to the entry point of the network, do one of the following, the first option being the preferred one:
UseCanonicalName On ServerName name of listener host Port port of listener host
httpd.conf file:
UseCanonicalName port Port port of listener host
Edit the proxy plug-in server configuration file:
oproxy.serverName.alias=name of listener host:port of listener host
The proxy plug-in supports SSL connections made between the client and the proxy host, but does not support SSL connections between the proxy and the back-end server. To implement the latter, set up the listener to receive SSL connections and start the back-end server in non-SSL mode. No changes to the proxy configuration are needed.
|
 Copyright © 2002, 2003 Oracle Corporation. All Rights Reserved. |
|