Skip Headers

Oracle® HTTP Server Administrator's Guide 10g Release 3 (10.1.3) B25211-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# A Using Oracle Application Server Proxy Plug-in

This appendix explains how the Oracle Application Server Proxy Plug-in (OracleAS Proxy Plug-in) enables you to use components in conjunction with a third-party HTTP listener. OracleAS Proxy Plug-in works with the Sun ONE Web Server Enterprise Edition on UNIX and Windows systems, or the Microsoft Internet Information Server (IIS) on Windows systems, to send requests to Oracle Application Server.

See Also: `http://www.oracle.com/technology/products/ias/ohs/htdocs/plugincerts.html` for complete certification information.

Topics discussed are:

- Overview

- Downloading OracleAS Proxy Plug-in

- Installing OracleAS Proxy Plug-in

- Using Application Server Control Console

- Configuring OracleAS Proxy Plug-in

- Configuring Sun ONE Listener to Use OracleAS Proxy Plug-in

- Configuring IIS Listener to Use OracleAS Proxy Plug-in

- OracleAS Proxy Plug-in Usage Notes

- Troubleshooting

## A.1 Overview

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

Figure A-1 OracleAS Proxy Plug-in

Description of "Figure A-1 OracleAS Proxy Plug-in"

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.

## A.2 Downloading OracleAS Proxy Plug-in

OracleAS Proxy Plug-in is available on the Oracle Application Server 10g Companion CD, which is included in your Oracle Application Server CD Pack.

## A.3 Installing OracleAS Proxy Plug-in

After downloading OracleAS Proxy Plug-in, place the appropriate configuration file and shared library in directories that the third-party listener can access.

On the Oracle Application Server 10g Companion CD, the files are located at `/plugins/solaris/` for UNIX and `/plugins/win32/` for Windows.

Table A-1 contains information about the shared libraries for OracleAS Proxy Plug-in.

Table A-1 OracleAS Proxy Plug-in Shared Libraries

Platform | File Name | Location and Description | Instructions
--- | --- | --- | ---
UNIX | `oracle_proxy.so` | `oracle_proxy.so` is the OracleAS Proxy Plug-in file for Sun ONE Web listener. It is located in the `/plugins/solaris/sunone` directory | To install the plug-in into the listener, place `oracle_proxy.so` in a directory to which the listener has read and execute privileges.
Windows | `oracle_proxy.dll` | `oracle_proxy.dll` is the OracleAS Proxy Plug-in file for the IIS Web listener. It is located in the `/plugins/win32/iis` directory. | To install the plug-in into the listener, copy `oracle_proxy.dll` to a directory the listener can access.
`oracle_proxy_sunone.dll` | `oracle_proxy_sunone.dll` is the OracleAS Proxy Plug-in file for Sun ONE Web listener. It is located in the `/plugins/win32/sunone` directory | To install the plug-in into the listener, copy `oracle_proxy_sunone.dll` to a directory the listener can access.

## A.4 Using Application Server Control Console

When you install Oracle Application Server, you can administer Oracle HTTP Server using Application Server Control Console. 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 Console so that it no longer appears there.

Oracle does not support monitoring or administering of non-Oracle HTTP Server listener with Application Server Control Console.

See Also: Oracle Enterprise Manager Concepts

## A.5 Configuring OracleAS Proxy Plug-in

There is one configuration file for OracleAS 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.

### A.5.1 Proxy Server Definition File

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 shared library file, and proxy log files in it.

Described in detail in Proxy Configuration File Parameters section, the proxy server definition file contains:

- Name value pairs that describe the servers that will be used to proxy requests to Oracle Application Server.

- Options for communicating with the servers.

- A set of rules that map URLs to the servers.

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.

Example A-1 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=/*

### A.5.2 Proxy Configuration File Parameters

The following proxy configuration file parameters are described in the subsequent sections:

- oproxy.serverlist

- oproxy.servername.hostname

- oproxy.servername.port

- oproxy.servername.alias

- oproxy.servername.resolveall

- oproxy.servername.urlrule

#### A.5.2.1 oproxy.serverlist

Lists all of the server names that the plug-in recognizes.

Category | Value
--- | ---
Parameter Type | string list
Allowable Values | Comma separated list of server names, one for each Oracle HTTP Server to which requests will be sent. All servers in the serverlist must also be defined in the file.
Default Value | None. At least one server name must be provided for the proxy to be functional.
Example | `oproxy.serverlist=ias1,ias2`

#### A.5.2.2 oproxy.servername.hostname

Defines the hostname to use when communicating with a specific server.

Category | Value
--- | ---
Parameter Type | string
Allowable Values | Valid hostname
Default Value | None
Example | `oproxy.ias1.hostname=www1.us.oracle.com`

#### A.5.2.3 oproxy.servername.port

Defines the port to use when communicating with a specific server.

Category | Value
--- | ---
Allowable Values | Valid port value
Default Value | 80
Example | `oproxy.ias1.port=7777`

#### A.5.2.4 oproxy.servername.alias

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 | `oproxy.``servername.hostname:oproxy.servername.port`
Example | `oproxy.ias1.alias=www.oracle.com:80`

#### A.5.2.5 oproxy.servername.resolveall

Directs the proxy plug-in to resolve the hostname to the backend server on every request. This enables DNS based failover or routing between the proxy plug-in and backend servers. The use of this parameter incurs the cost of going to the DNS server for every incoming request, and hence should only be used if the mapping from hostname to IP address will change dynamically.

Category | Value
--- | ---
Allowable Values | true or false
Default Value | false
Example | `oproxy.ias1.resolveall=true`

#### A.5.2.6 oproxy.servername.urlrule

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.

- Exact matches: One URL is mapped to a server.

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

- Context matches: A set of URLs with a common prefix or context are all mapped to a server. For example, `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 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

- Suffix matches: All files with a common file extension are mapped to a server.

  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.

Note: For the`oproxy.``servername``.urlrule,` when multiple rules apply to the same URL, the following precedence applies: Exact matches Longest context match plus suffix match Longest context match Some examples of the precedence are: `/foo/bar/index.html would take precedence over /foo/bar/*` `/foo/bar/*.jsp would take precedence over /foo/bar/*` `/foo/bar/* would take precedence over /foo/*`

### A.5.3 Defining OracleAS Proxy Plug-in Behavior

In the proxy server definition file, you define which servers and URLs to proxy to the plug-in.

1. In the first line of the file, specify the list of all the servers that can be used by the plugins. For example:

       oproxy.serverlist=ias1,ias2

2. Set the relevant properties (hostname, port, and server alias) for each server. For example:

       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.

3. Set the `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.

## A.6 Configuring Sun ONE Listener to Use OracleAS Proxy Plug-in

This section provides proxy plug-in configuration instructions for Sun ONE Enterprise Server listener on UNIX and Windows systems.

Notes: If you are configuring the Sun ONE listener on Windows, use forward slashes (/) in all paths. The default configuration files for Sun ONE route all incoming requests for the URI `/servlet` to the Sun ONE servlet handler. The OracleAS Proxy Plug-in does not override the Sun ONE server's configuration settings. You must ensure that the URL mappings to the OracleAS Proxy Plug-in are distinct from the URL mappings to the Sun ONE servlet engine.

1. Open the `magnus.conf` file in version 6, or `obj.conf` in version 4 in the Sun ONE listener `/config` directory.

2. Add the load-modules line:

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

3. Add the configuration parameters line:

       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.

4. Add the following line to the `<Object name=default>` section of the `obj.conf` file, before all other lines beginning with the word `ObjectType`:

       ObjectType fn=op_objecttype

5. Add the following line before all other lines that begin with the word `"Service"`:

       Service type="oracle/proxy" fn="op_service"

6. Start the listener using the GUI or the shell script.

## A.7 Configuring IIS Listener to Use OracleAS Proxy Plug-in

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, perform the following steps:

1. From the Start menu, select Run.

2. In the run dialog box, type `regedit` and click OK.

   The Registry Editor window opens.

3. In the Registry Editor window, expand the `HKEY_LOCAL_MACHINE` folder (click the + preceding its name).

4. Expand the `SOFTWARE` folder (click the + preceding its name).

5. Click the `ORACLE` folder.

6. From the Edit menu, select New, then Key.

   A new folder is added under the `ORACLE` folder with the name `New Key #1`.

7. Type `IIS` `Proxy` `Adapter` for the key name.

8. From the Edit menu, select New, then String Value.

   A new value is added in the right window pane with the name `New Value #1`.

9. Type `server_defs` for the value name.

10. From the Edit menu, select Modify. The Edit String dialog box appears.

11. In the Value data field, type the full path of your proxy server definition file. Click OK.

12. Specify `log_file` and `log_level` using the procedure specified in steps 8-11. This is optional.

    1. Add a string value with the name `log_file` and the desired location of the log file (for example, `d:\proxy\proxy.log`)

    2. Add a string value with the name `log_level` and a value for the desired log level. Valid values are debug, inform, error and emerg.

13. Using the IIS management console, add a new virtual directory to your IIS Web site with the same physical path as that of `oracle_proxy.dll`. Name the directory `oproxy` and give it execute access.

14. Using the IIS management console, add `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`).

15. Restart IIS (stop and then start the IIS Server), ensuring that the `oproxy` filter is marked with a green upward arrow.

    Note: To restart IIS, you must stop all of the IIS services through the control panel, or restart the computer. This is the only way to ensure that the `.dll` is reloaded. Restarting IIS through the management console is not sufficient.

## A.8 OracleAS Proxy Plug-in Usage Notes

This section highlights development and usage practices to consider when developing an application that runs behind the OracleAS Proxy Plug-in. Some of these also have relevance when enabling an application to run behind Oracle Application Server Web Cache.

- Check for configurations based on the Oracle HTTP Server being the entry point into the network.

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

- Avoid returning non-relative links in HTML, that is, avoid embedding host names into HTML unless the link is external to the Web site.

  This includes static HTML pages, dynamic pages generated by servlets, JSPs, PL/SQL, and so on. 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.

- Avoid returning host and port information in applications (such as applets or javascript) downloaded to the client.

  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.

- Ensure that all URLs within an application can be easily mapped to a set of rules that the proxy can use.

  In order to successfully proxy all requests for an application, the OracleAS 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:

  - Change these common links to something that will not conflict with applications that might already be deployed on the third-party listener.

  - Instruct the user to copy the necessary content to the third-party listener's directory structure. For performance reasons, it is a good idea to have the third-party listener handle static `.gif` and `.jpg` files anyway, but it requires extra effort.

## A.9 Troubleshooting

This section describes common problems and possible solutions.

Listener Fails to Start

- Ensure that you have the newest version of the OracleAS Proxy Plug-in.

- Verify that your listener configuration is set up correctly. (The IIS listener may need to be restarted in order to make the filter work properly.) A proxy server definition file must exist.

  See Also: "Proxy Server Definition File" for a description of this file and parameter requirements.

- Check for problems in the proxy server definition file. Each server in the serverlist line must be defined later in the file, and you must have at least one server defined. If a server name is listed but not defined, the listener may not start (although the reverse is not true). Ensure that there are no typographical errors or missing quotes in the proxy server definition file.

- For Sun ONE 6.0 on UNIX and Windows: Ensure that `Init` lines are added to the `magnus.conf` file and `ObjectType` and `Service` lines are added to the `obj.conf` file.

Listener Returns Incorrect URLs

- Verify that changes to the proxy server definition file have been saved and the listener has been restarted.

- Ensure that there are no typographical errors in the proxy server definition file.

- Ensure that the `urlrule` parameter is set up correctly, and consider whether the stripcontext option should be set to true.

- Verify that the `serverlist` line in the proxy server definition file specifies the back-end server you are trying to reach.

- Verify that the back-end server is running, and that the file you are attempting to retrieve exists and is accessible on the back-end server.

- Verify that the host, port and `urlrule` parameters in the proxy server definition file target the correct area on the back-end server.

- Ensure that client requests are being sent to the correct port on the third-party listener machine.

- Check the listener log files, the proxy log (may need to be turned on in "debug" mode, and may require restarting the listener), and the back-end server logs to verify that requests are getting through.

Changes Made to Proxy Server Definition File are Not Reflected

- Ensure that you have saved the proxy server definition file and restarted the listener.

- For IIS: To pick up the changes, you must stop and start the WWW Publishing Service from the Control Panel. This takes a few minutes.

IIS Listener Displays Incomplete Pages or Garbled Characters

Do not display an IIS pages with a Sun ONE browser.

Parsing Error Occurs with Sun ONE 6.0

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.

"File Not Found" Error Occurs

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

See Also: "oproxy.servername.urlrule"

Partial URL Requests Return Unexpected Results

The IIS and Sun ONE servers auto-complete URLs differently. Requests of "h`ttp://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.

See Also: "oproxy.servername.urlrule"

Sun ONE Server Returns "Server Error" with "/servlet" Request

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.

Server Returns Page with Broken Image Links

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

Unexpected Pages are Displayed

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.

REMOTE_ADDR Contains Unexpected IP Address

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.

Redirects Go To Network Entry Point

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:

- Set the following directives in the `httpd.conf` file:

      UseCanonicalName On
      ServerName name of listener host
      Port port of listener host

- Set the following directives in the `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

SSL Requests Yield Unexpected Results

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.