A
Using the Oracle9iAS Proxy Plug-in

This appendix explains how the Oracle9iAS Proxy Plug-in enables you to use Oracle9iAS components in conjunction with a third-party HTTP listener. The Oracle9iAS Proxy Plug-in works with the Netscape iPlanet 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 Oracle9iAS.

This appendix contains the following topics:

• Overview

• Downloading the Plug-in

• Installing the Plug-in

• Configuring the Plug-in

• Configuring the iPlanet Listener to Use the Proxy Plug-in

• Configuring the IIS Listener to Use the Proxy Plug-in

• Using Single-Sign On with the Plug-in
  • Configuring Single Sign-On Plug-Ins

  • Configuring the iPlanet Listener for Single Sign-on

  • Configuring the IIS Listener for Single Sign-On

  • Obtaining an Obfuscated Single Sign-On Server Configuration File

• Proxy Plug-In Usage Notes

Overview

The Oracle9iAS Proxy Plug-in is a reverse HTTP proxy. It forwards incoming HTTP requests to an Oracle9iAS instance as shown in Figure A-1.

Figure A-1 Oracle9iAS Proxy Plug-in

Text description of the illustration proxya.gif

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 (mods) are plugged into the Oracle HTTP Server.

The Oracle HTTP Server can mimic the address and port that the third-party listener is using. That is, when sending a request to the 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.

Downloading the Plug-in

The plug-in is distributed on the Integration CD, and available on OTN at

http://otn.oracle.com

Installing the Plug-in

There is no installation procedure for the proxy plug-in. After downloading the plug-in, you need only place the configuration files and shared library in directories that the third-party listener can access.

Installing the Plug-in on UNIX Systems

The plug-in consists of a single shared library, oracle_proxy.so. To install the plug-in into the listener, simply place the library in a directory to which the listener has read and execute privileges.

Installing the Plug-in on Windows Systems

The plug-in consists of a single dll, oracle_proxy.dll for IIS, or oracle_proxy_nes.dll for Netscape. To install this plug-in, copy the .dll to a directory the listener can access.

Configuring the Plug-in

There are three configuration files for the Oracle9iAS Proxy Plug-in, one to control the proxy functionality and two to control the single sign-on functionality. The presence of the configuration file in the web server's file system makes the functionality active.

You may also need to modify configuration files specific to the third-party listener to install the plugin on to these listeners. Configuration instructions for those files are not included here.

Proxy Configuration File

This file must reside in a directory that is readable by the third-party listener. Described in detail in Table A-1, this file contains:

• Name value pairs that describe the servers that will be used to proxy requests to Oracle9iAS.

• Options for communicating with the servers.

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

  Table A-1 Proxy Configuration File Parameters  

  Parameter Name	Description
  oproxy.serverlist	This parameter lists all of the server names that the plug-in will recognize. 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
  oproxy.servername.hostname	This parameter defines the hostname to use when communicating with a specific server. Parameter Type: string Allowable Values: Valid hostname. Default Value: None. Example: oproxy.ias1.hostname=www1.us.oracle.com
  oproxy.servername.port	This parameter defines the port to use when communicating with a specific server. Allowable Values: Valid port value. Default Value: 80 Example: oproxy.ias1.port=7777
  oproxy.servername.alias	This parameter 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. Parameter Type: string Allowable Values: host:port Default Value: oproxy.servername.hostname:oproxy.servername.port Example: oproxy.ias1.alias=www.oracle.com:80
  oproxy.servername.urlrule	This parameter describes a URL or set of URLs that will be redirected to this server. A given server can have any number of urlrule properties assigned to it. 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 config 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 below for completeness of the example. Example: The 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 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.
  	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/*

Defining Proxy Plug-in Behavior

In the proxy configuration file, you define which servers and URLs to proxy to the plugin.

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 via HTTP/1.1 to the specified server.

Configuring the iPlanet Listener to Use the Proxy Plug-in

This section provides proxy plug-in configuration instructions for the Netscape iPlanet Enterprise Server listener on UNIX and Windows NT systems.

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

1. Open the magnus.conf file (version 6) or obj.conf (version 4) in the Netscape listener /config directory.

2. Add the load-modules line:

   For UNIX:

   Init fn="load-modules" shlib="/path/oracle_proxy.so" funcs=op_init,op_
   objecttype,op_service
   

   For Windows NT:

   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.

3. Add the configuration parameters line:

   Init fn="op_init" server_defs="/path/config/servers" log_
   file="/path/logs/oproxy.log" log_level=error
   

   where /path/ is the path to the server definition and log files. The 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).

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.

Configuring the IIS Listener to Use the Proxy Plug-in

This section provides proxy plug-in configuration instructions for the IIS listener on Windows systems. To configure the plug-in:

1. Create a new registry key named HKEY_LOCAL_MACHINE\SOFTWARE\Oracle\IIS Proxy Adapter

2. Specify the location of your server definition file by adding a string value with the name server_defs, and a value pointing to the location of your definition file.

3. (Optional) Specify log_file and log_level:
   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.

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

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

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

Using Single-Sign On with the Plug-in

In addition to the proxy functionality, the proxy plug-in includes the same functionality provided by mod_osso to the Oracle HTTP Server to support single sign-on. With single sign-on, users need authenticate only once to the web server; thereafter, the user name and password are relayed invisibly to Oracle9iAS applications.

If you want to use single sign-on functionality, you must first install the database Required Support Files libraries (v9.0.1.3) in order to get the necessary security libraries.

Configuring Single Sign-On Plug-Ins

Oracle Single Sign-On (OSSO) can be used with iPlanet and IIS web servers. OSSO implements the basic functionalities of mod_osso, the single sign-on module for the Oracle HTTP Server. Features not implemented in the current release include:

• Dynamic authentication

• Global logout

• Basic authentication for legacy applications.

Both iPlanet and IIS OSSO plug-ins use the same formatted osso_plugin.conf file. You must create this file and put it in a location that the listener can access.

OSSO Configuration File Examples

This section contains examples of entries from the OSSO configuration file osso_plugin.conf.

Note: The osso_plugin.conf file must be referenced by the obj.conf file, configuration parameters line, as follows: Init fn="osso_init" osso_properties="/path/config/osso_ plugin.conf" log_file="/path/debug.log" log_level=error This line can also specify a log file and log level to log messages from the plug-in (optional).

LoginServerFile = "/path/config/sso_conf"
HardTimeOut = 1000

In the LoginServerFile directive above, path is the iPlanet server root directory.

<OSSO /private/hello.html>
 IpCheck = true;
 HardTimeOut = 10000
</OSSO>
 
<OSSO /private1/*>
 IpCheck = false
</OSSO>
 
<OSSO /private2/*.jsp>
 IpCheck = false
 HardTimeOut = 100
</OSSO> 

OSSO directives

This section describes the OSSO directives.

LoginServerFile

Specifies the location of the Single Sign-On Server configuration file that provides all the information about the Single Sign-On Server, such as version, cipher key, etc. This Single Sign-On Server configuration file is obfuscated. See "Obtaining an Obfuscated Single Sign-On Server Configuration File".

Currently, only one Single Sign-On Server is allowed for all the protected resources, so you cannot use this directive on a per-resource basis. You must provide one and only one Single Sign-On Server configuration file.

IpCheck

Specifies whether OSSO should check the IP address of each request when it examines the cookie. Valid values are true and false. Setting IpCheck to true prevents cookies being stolen.

Example:

IpCheck = true  

Note: Set IpCheck to false if you have a proxy server or firewall between your iPlanet server and your clients' browser.

HardTimeout

Specifies the lifetime (in seconds) of the cookie for the protected resource. After this amount of time, the user will have to authenticate again.

Example:

HardTimeout = 100

Specifying Protected URIs

You can specify URIs to protect in several ways:

Exact Context

This option identifies a particular file as a protected resource, for example:

/examples/Hello.html

Context Based

This option identifies a directory as a protected resource, for example:

/examples/*

Context and Suffix

This option identifies files with a certain extension in a particular directory as a protected resource, for example:

/examples/*.jsp 

Configuring the iPlanet Listener for Single Sign-on

This section provides instructions on configuring the iPlanet Enterprise Server listener to use the OSSO plug-in.

1. Open the obj.conf file in the Netscape listener /config directory.

2. Add the load-modules line:

   Init fn="load-modules" shlib="/path/oracle_proxy.so" funcs="osso_
   init,oracle_single_sign_on,osso_redirect,osso_success_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="osso_init" osso_properties="/path/config/osso_plugin.conf" log_
   file="/path/debug.log" log_level=error
   

   where /path/ is the iPlanet server root directory. This line contains the location of an OSSO definition file that contains all of the configuration information for the servers that the OSSO plug-in will use. This line can also specify a log file and log level to log messages from the plug-in (optional).

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

   AuthTrans fn="oracle_single_sign_on"
   

5. Add the following line to the Object name=default section before all other lines that begin with the word Service:

   Service type="oracle/sso_redirect" fn="osso_redirect_service"
   

6. Add the following lines:

   <Object ppath="/path/osso_login_success">
     Service fn="osso_success_service"
   </Object> 
   

   where path is the path of your document root (e.g., home/me/iplanet/docs/). This should be the same path as named in

   NameTrans fn=document-root root=/.../iplanet/docs
   

7. Change the LD_LIBRARY_PATH variable in your start script to include the location of libclntsh.so.

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

Usage Notes for Netscape/iPlanet Enterprise Server Version 6.0

For version 6.0, the same shared library can be used as with version 4.1. The configuration is virtually the same, but the configuration files for Netscape have changed slightly in version 6.0. In this version, the two lines beginning with Init that need to be added must be added at the end of the magnus.conf file rather than to the obj.conf file. The other two lines that should be added to obj.conf remain the same.

Configuring the IIS Listener for Single Sign-On

This section provides instructions on configuring the IIS Listener to use the OSSO plug-in. The plugin consists of a single dll, oracle_osso.dll. To install the plugin, copy the .dll to the computer on which IIS resides and perform the following steps:

1. Edit your registry to create a new registry key named HKEY_LOCAL_MACHINE\SOFTWARE\Oracle\IIS OSSO Adapter.

2. Specify the location of your osso configuration file by adding a string value with the name cfg_file and a value pointing to the location of your definition file.

3. (Optional) Specify a log_file and log_level:
   1. Add a string value with the name log_file and the desired location of the log file (for example, d:\osso\osso.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.

4. Using the IIS management console, add a new virtual directory to your IIS web site with the same physical path as that of oracle_osso.dll. Name the directory osso and give it execute access.

5. Using the IIS management console, add oracle_osso.dll as a filter in your IIS web site. The name of the filter should be osso and its executable must point to the directory containing oracle_osso.dll (for example, d:\osso\oracle_osso.dll).

6. Restart IIS (stop and then start the IIS Server), ensuring that the oproxy filter is marked with a green up-pointing 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).

Obtaining an Obfuscated Single Sign-On Server Configuration File

Follow these steps to obtain an obfuscated Single Sign-On Server configuration file for the iPlanet server.

1. Install the Oracle9iAS core components on the computer on which the iPlanet server resides.

2. Register the iPlanet server with a Single Sign-On server using the command below. If entered line by line on a terminal, each line must end with the backslash character. Command arguments are shown in italics; you must supply valid values. Arguments are described in Table A-2, "SSO Registrar Command Arguments".

   $ORACLE_HOME/jdk/bin/java -jar $ORACLE_HOME/sso/lib/ossoreg.jar \
   -oracle_home_path $ORACLE_HOME \
   -host login server database hostname \
   -port login server database port \
   -sid login server database sid \
   -site_name name of iplanet server \
   -success_url http://iplanet server hostname:port/osso login success url \
   -cancel_url http://iplanet server hostname:port/cancel url \
   -logout_url http://iplanet server hostname:port/osso logout success url \
   -home_url http://iplanet server hostname:port/home url \
   [-admin_id administrator user id] \
   [-admin_info administrator information] \
   -config_mod_osso TRUE \
   -virtualhost \
   -u userid \
   -sso_server_version v1.2 \
   -text_file $ORACLE_HOME/cleartext sso configuration file \
   -config_file $ORACLE_HOME/Apache/Apache/conf/osso/sso_conf \
   

3. Copy the generated sso_conf file to the iPlanet root directory

4. Ensure that the LoginServerFile directive in the osso_plugin.conf file specifies the generated sso_conf file.

SSO Registrar Command Arguments

Table A-2 lists the command arguments for the SSO Registrar.

Table A-2 SSO Registrar Command Arguments

Argument	Description
-oracle_home_path	Absolute path to the Oracle home.
-site_name	Name of the site, typically expressed as the contiguous string host:port.
-success_url	URL to the routine responsible for establishing the partner application session and session cookies. The URL is: http://iplanet server hostname:port/osso_login_success
-cancel_url	URL to which the SSO server redirects when the user cancels authentication.
-admin_id	User name of the mod_osso administrator. This argument is optional.
-admin_info	Information associated with the administrator's user name, such as e-mail address. This argument is optional.
-config_ mod_osso	If set to TRUE, this parameter indicates that the application being registered is mod_osso. This argument is necessary to generate the sso_conf file.
-u	Specifies the user name under which the Oracle HTTP Server was started. In the case of the iPlanet server, it is the name of the user under which the iPlanet server will run (specified during iPlanet server configuration). Note the difference between the -u value specified for the Oracle HTTP Server and that specified for the iPlanet server: For the Oracle HTTP Server, -u is the user that started the server. For the iPlanet server, -u is the user under which the server answers client requests. You can specify -u root for the Oracle HTTP Server. However, Oracle Corporation recommends against specifying -u root when configuring an iPlanet server (and, by implication, not to use -u root when registering the iPlanet server with the SSO server. This argument is optional. The default is the user name under which the SSORegistrar tool is run. In this case, the Oracle HTTP Server must be started under that user name, and the iPlanet server must be configured to answer client requests under that name.
-sso_server_version	Must be set to v1.2 in Oracle9iAS Release 2.
-virtualhost	Must be specified when registering an iPlanet server. However, it is optional when registering Oracle HTTP Server. If it is left unspecified, the Oracle HTTP server belongs to a cluster.
-text_file	Specifies a path to a temporary version of the mod_osso configuration file. It is optional, and the default location is: ORACLE_HOME/Apache/Apache/conf/osso/osso.txt.
-config_file	Specifies a path to the mod_osso configuration file. It must be specified if -virtualhost is present. For this release, its value can only be set to: ORACLE_HOME/Apache/Apache/conf/osso/sso_osso.

Proxy Plug-In Usage Notes

This section highlights development and usage practices to consider when developing an application that will run behind the Oracle9iAS Proxy Plug-in. Some of these also have relevance when enabling an application to run behind Oracle9iAS 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 Oracle9iAS Proxy Plug-in and 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 Oracle9iAS.

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

  This includes static HTML pages, dynamic pages generated by servlets, JSPs, PL/SQL, etc. Examine all code that obtains the server name of the 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 the 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 Oracle9iAS Proxy Plug-in must have a complete description of the URL space for that application. Each Oracle9iAS 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 won't conflict with applications that might already be deployed on the third-party listener, or

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

Troubleshooting

This section describes common problems and possible solutions.

Listener Fails To Start

• Ensure that you have the newest version of the Oracle9iAS 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 server definition file must exist and cannot be empty.

• Check for problems in the 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 server definition file.

• For iPlanet 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 server definition file have been saved and the listener has been restarted.

• Ensure that there are no typographical errors in the 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 server definition file specifies the back-end server you're trying to reach.

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

• Verify that the host, port and urlrule parameters in the 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 Server Definition File Are Not Reflected

• Ensure that you have saved the 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 Netscape browser.

Parsing Error Occurs with iPlanet 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 the oproxy.servername.urlrule parameter, stripcontext option, in the table "Proxy Configuration File Parameters".

Partial URL Requests Return Unexpected Results

The IIS and iPlanet servers auto-complete URLs differently. Requests of "http://serverName", "http://serviceman/", and "http://serviceman/index.html" do not necessarily return the same results on different platforms. The oproxy.servername.urlrule parameter (described in the table "Proxy Configuration File Parameters") can be used to work around this problem.

iPlanet Server Returns "Server Error" With "/servlet" Request

The default iPlanet configuration maps any URL requests to "/servlet" to its own servlet handler. You must edit the server definition file, or change the iPlanet configuration to correct this.

Server Returns Page With Broken Image Links

If you use an exact urlrule parameter (e.g. "urlrule=/*.html") in the server definition file (or a similar scenario), the server will retrieve 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 Netscape 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:

Solution 1 (Preferred)

Set the following directives in the httpd.conf file:

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

Solution 2

Set the following directives in the httpd.conf file:

UseCanonicalName port 
Port port of Listener computer

Edit the proxy plug-in server configuration file:

oproxy.serverName.alias=name of listener computer:port of istener computer

SSL Requests Yield Unexpected Results

The proxy plug-in supports SSL connections made between the client and the proxy computer, 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.