|
Oracle® HTTP Server Administrator's Guide
10g Release 2 (10.1.2) B14007-03 |
|
 Previous |
 Next |
|
Oracle® HTTP Server Administrator's Guide
10g Release 2 (10.1.2) B14007-03 |
|
|
Previous |
Next |
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:
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.
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.
OracleAS Proxy Plug-in is available on the Oracle Application Server 10g Companion CD, which is included in your Oracle Application Server CD Pack.
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 |
|
To install the plug-in into the listener, place |
|
|
Windows
|
|
To install the plug-in into the listener, copy |
|
|
|
To install the plug-in into the listener, copy |
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.
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.
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=/*
The following proxy configuration file parameters are described in the subsequent sections:
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
|
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
|
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
|
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
|
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
|
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:
Some examples of the precedence are:
|
In the proxy server definition file, you define which servers and URLs to proxy to the plug-in.
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
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.
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.
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 |
Open the magnus.conf file in version 6, or obj.conf in version 4 in the Sun ONE listener /config directory.
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.
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).
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
Add the following line before all other lines that begin with the word "Service":
Service type="oracle/proxy" fn="op_service"
Start the listener using the GUI or the shell script.
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:
From the Start menu, select Run.
In the run dialog box, type regedit and click OK.
The Registry Editor window opens.
In the Registry Editor window, expand the HKEY_LOCAL_MACHINE folder (click the + preceding its name).
Expand the SOFTWARE folder (click the + preceding its name).
Click the ORACLE folder.
From the Edit menu, select New, then Key.
A new folder is added under the ORACLE folder with the name New Key #1.
Type IIS Proxy Adapter for the key name.
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.
Type server_defs for the value name.
From the Edit menu, select Modify. The Edit String dialog box appears.
In the Value data field, type the full path of your proxy server definition file. Click OK.
Specify log_file and log_level using the procedure specified in steps 8-11. This is optional.
Add a string value with the name log_file and the desired location of the log file (for example, d:\proxy\proxy.log)
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.
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.
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).
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.
|
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.
This section describes common problems and possible solutions.
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.
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.
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".
Partial URL Requests Return Unexpected Results
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.
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.
