Release Notes for Sun Java™ System Web Server 6.1 Add-Ons
Reverse Proxy Plugin 6.1

Release Notes for Sun Java™ System Web Server 6.1 Add-Ons
Reverse Proxy Plugin

Version 6.1

Part Number 819-0902-05

March 2005

These release notes contain important information available at the time of release of Sun Java™ System Web Server 6.1 Reverse Proxy Plugin, including information about server application functions (SAFs), installation, configuration, technical notes, and pointers to additional resources. Review the release notes prior to installing and configuring your software, and then periodically thereafter for the most up-to-date information.

Complete Sun Java System Web Server 6.1 documentation can be found at the following location:
http://docs.sun.com/db/prod/s1websrv#hic

These release notes contain the following sections:

Introduction

The Reverse Proxy Plugin is a NSAPI plugin designed for use with the Sun Java System Web Server 6.1 SP3 and later Service Packs. This add-on allows the Web Server to act as a non-caching HTTP reverse proxy for specified URIs.

A reverse proxy is a proxy that appears to be a web server (origin server) to clients but in reality forwards the requests it receives to one or more origin servers. Because a reverse proxy presents itself as an origin server, clients do not need to be configured to use a reverse proxy. By configuring a given reverse proxy to forward requests to multiple similarly configured origin servers, a reverse proxy can operate as an application level software load balancer. In a typical deployment one or more reverse proxies will be deployed between the browsers and the origin servers.

The Reverse Proxy Plugin can be used in conjunction with existing Sun Web Server features such as on-the-fly gzip compression, output filters, advanced Access Control Lists, and so on.

The Reverse Proxy Plugin includes support for the following features:

HTTP/1.0 and HTTP/1.1 Compliance

The Reverse Proxy Plugin will issue HTTP/1.1 requests to origin servers and will accept HTTP/1.0 responses to requests. It will not upgrade incoming HTTP/1.0 requests to HTTP/1.1 in ways that are incompatible with HTTP/1.0 (for example, it will not add a Transfer-encoding: chunked header to a request).

Credential Pass-through

The Reverse Proxy Plugin will pass through Basic-Auth and Digest-Auth credentials presented by the client. It will encode client certificates from the client and present them in proprietary headers that an appropriately coded application on the origin server can utilize.

Authentication to Origin Servers

The Reverse Proxy Plugin can be configured to present its own credentials to an origin server. The Reverse Proxy Plugin is capable of presenting Basic-Auth or utilizing a specified certificate nickname.

Data Encryption

The Reverse Proxy Plugin is able to utilize SSLv2, SSLv3 and TLS when making requests to origin servers.

Session Stickiness

The Reverse Proxy Plugin is able to be configured to recognize "sticky cookies," and can have the name of the sticky cookies be configured.

Simple Load Balancing

The Reverse Proxy Plugin will distribute load to several configured origin servers.

Granular Error Logging

The Reverse Proxy Plugin takes advantage of the Web Server's granular error logging capabilities (config, failure, warning, fine, finer, and finest). See the Web Server's documentation for more detail.

Server Application Functions (SAFs)

The Reverse Proxy Plugin provides the following Server Application Functions (SAFs):

auth-passthrough

The auth-passthrough AuthTrans SAF inspects an incoming HTTP request for client information encoded by a service-passthrough function running on an intermediate server. The client information includes the following:

When auth-passthrough detects encoded client information, it instructs the server to treat the request as if it had arrived directly from the originating client instead of via an intermediate server running service-passthrough.

The auth-passthrough SAF is optional. When used, auth-passthrough is used on the server instance that receives the request forwarded by service-passthrough.

Since auth-passthrough makes it possible to override information that may be used for authentication (for example, the IP address of the original request), it is important that only trusted clients and servers be allowed to connect to a server running auth-passthrough. As a minimal precaution, only servers behind a corporate firewall should run auth-passthrough; no Internet-accessible server should run auth-passthrough. Further, if this information about the originating client is not required, auth-passthrough should not be used.

The following obj.conf snippet demonstrates the use of auth-passthrough (note that these lines are not indented in a real obj.conf):

<Object name="default">
AuthTrans fn="auth-passthrough"
...
</Object>

check-passthrough

The check-passthrough ObjectType SAF checks to see if the requested resource (for example, the HTML document or GIF image) is available on the local server. If the requested resource does not exist locally, check-passthrough sets the type to indicate that the request should be passed to another server for processing by service-passthrough.

The check-passthrough SAF accepts the following parameters:

service-passthrough

The service-passthrough Service SAF forwards a request to another server for processing.

The service-passthrough SAF accepts the following parameters:

When multiple remote servers are configured, service-passthrough chooses a single remote server from the list on a request-by-request basis. If a remote server cannot be contacted or returns an invalid response, service-passthrough sets the status code to 502 Bad Gateway and returns REQ_ABORTED. This will return an error to the browser. This error can be customized in the Web Server by configuring a customized response for the 502 error code.

When user and password are specified, service-passthrough will use these credentials to authenticate to the remote server using HTTP basic authentication. When one or more of the servers in the servers parameter are configured with a https:// prefix, client-cert-nickname specifies the nickname of the client certificate service-passthrough will use to authenticate to the remote server.

Note that service-passthrough generally uses HTTP/1.1 and persistent connections for outbound requests with the following exceptions:

In addition, service-passthrough encodes information about the originating client in the headers named by the ip-header, cipher-header, keysize-header, secret-keysize-header, ssl-id-header, issuer-dn-header, user-dn-header, and auth-cert-header parameters (removing any client-supplied headers with the same name) before forwarding the request. Applications running on the remote server may examine these headers to extract information about the originating client.

Installing the Reverse Proxy Plugin

The Reverse Proxy Plugin is available for use with the Sun Java System Web Server 6.1 SP3 or later Service Packs.

This section includes the following topics:

Package Contents

The contents of the platform specific packages are:

Solaris, Linux, AIX:

HP-UX:

Windows:

Installing on Solaris, Linux, HP-UX and AIX Using tar Packaging

$ gzip -d sun-webserver61-passthrough-{sol|lin|hpux|aix}.tar.gz
;; Uncompress the tar archive,
;; where {sol|lin|hpux|aix} reflects
;; the operating system
;; environment the library will
;; be used

$ tar xvf sun-webserver61-passthrough-{sol|lin|hpux|aix}.tar

;; Extract the tar archive

Please refer to "Configuring the Reverse Proxy Plugin."

Installing on Windows

$ unzip sun-webserver61-passthrough-win.zip
;; Uncompress the ZIP archive

Please refer to "Configuring the Reverse Proxy Plugin."

Installing on Solaris Using SVr4 Packaging

$ su
;; root access is required to install
;; SVr4 packages

$ cd <path/to/package>

;; Change directory to where the package
;; is located

# pkgadd -d .

;; Install SUNWwbsvr-passthrough.pkg package

NOTE: This will place the shared object and README in: /opt/SUNWwbsvr/plugins/passthrough

Please refer to "Configuring the Reverse Proxy Plugin."

Installing on Linux using RPM Packaging

$ su
;; root access is required to
;; install RPM packages

$ cd <path/to/package>

;; Change directory to where
;; the package is located

# rpm -iUvh sun-webserver-passthrough.rpm

;; Install
;; sun-webserver-passthrough.rpm
;; package

NOTE: This will place the shared object and README in /opt/sun/webserver/plugins/passthrough

Please refer to "Configuring the Reverse Proxy Plugin."

Configuring the Reverse Proxy Plugin

The Reverse Proxy Plugin needs to be initialized in the Sn Java System Web Server magnus.conf file and configured in the corresponding obj.conf file.

This section includes the following topics:

magnus.conf

</path/to/sharedobject> is the path where the shared object was installed, including the shared object itself.

Note that the path elements are "/" regardless of the operating system.

Init fn="load-modules" shlib="</path/to/sharedobject>

obj.conf

Configuration of the obj.conf will vary depending on the intended use. See the Sun Java System Web Server documentation for use and syntax of the obj.conf.

Example 1

This configuration will proxy the URI "/example" if it does not exist locally. A local copy of "/example" will be preferred to a remote copy:

<Object name="default">
# Assign the URI "/example" (and any more specific URIs;
# /example/foo.html, /example/qwe.jsp, etc) the object name
# "server.example.com"
NameTrans fn="assign-name"

from="/example(|/*)"
name="server.example.com"
...
</Object>

# Execute these instructions for any resource with the assigned name
# "server.example.com"
<Object name="server.example.com">

# Check to see if a local copy of the requested resource exists. Only
# proxy the request if there is not a local copy.
ObjectType fn="check-passthrough"

type="magnus-internal/passthrough"

# Proxy the requested resource to the URL
# "http://server.example.com:8080" only if the "type" has been set to
# "magnus-internal-passthrough"
Service type="magnus-internal/passthrough"

fn="service-passthrough"
servers="http://server.example.com:8080"
</Object>

Example 2

This configuration will proxy all requests for the URI "/app" without first checking for a local version. The Reverse Proxy Plugin will provide its own credentials via Basic-Auth to the origin server.

<Object name="default">
# Assign the URI "/app" (and any more specific URIs;
# /app/foo.html, /app/qwe.jsp, etc) the object name
# "server.example.com"
NameTrans fn="assign-name"

from="/app(|/*)"
name="server.example.com"
...
</Object>

# Execute these instructions for any resource with the assigned name
# "server.example.com"
<Object name="server.example.com">

# Proxy the requested resource to the URL
# "http://server.example.com:8080"
Service fn="service-passthrough"

servers="http://server.example.com:8080"
user="blues"
password="j4ke&elwOOd"
</Object>

How to Report Problems and Provide Feedback

If you have problems with Sun Java System Web Server 6.1 Reverse Proxy Plugin, contact Sun customer support using one of the following mechanisms:

So that we can best assist you in resolving problems, please have the following information available when you contact support:

  • Description of the problem, including the situation where the problem occurs and its impact on your operation
  • Machine type, operating system version, and product version, including any patches and other software that might be affecting the problem
  • Detailed steps on the methods you have used to reproduce the problem
  • Any error logs or core dumps

Sun Welcomes Your Comments

Sun is interested in improving its documentation and welcomes your comments and suggestions. Send your comments to Sun using the "Send comments" link at:  http://docs.sun.com/

Please include identifying information with your comments, such as the book’s part number and title.

Additional Sun Resources

Useful Sun ONE information can be found at the following locations:

Copyright � 2004 Sun Microsystems, Inc. All rights reserved. Sun Microsystems, Inc. has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without limitation, these intellectual property rights may include one or more of the U.S. patents listed at http://www.sun.com/patents and one or more additional patents or pending patent applications in the U.S. and in other countries. SUN PROPRIETARY/CONFIDENTIAL. U.S. Government Rights - Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supplements. Use is subject to license terms. This distribution may include materials developed by third parties. Portions may be derived from Berkeley BSD systems, licensed from U. of CA. Sun, Sun Microsystems, the Sun logo, Java and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the U.S. and other countries.

 

Copyright � 2004 Sun Microsystems, Inc. Tous droits r�serv�s. Sun Microsystems, Inc. d�tient les droits de propri�t� intellectuels relatifs � la technologie incorpor�e dans le produit qui est d�crit dans ce document. En particulier, et ce sans limitation, ces droits de propri�t� intellectuelle peuvent inclure un ou plusieurs des brevets am�ricains list�s � l'adresse http://www.sun.com/patents et et un ou des brevets des applications de brevet en attente aux Etats - Unis et dans les autres pays. Propri�t� de SUN/CONFIDENTIEL. L'utilisation est soumise aux termes du contrat de licence. Cette distribution peut comprendre des composants d�velopp�s par des tierces parties. Des parties de ce produit pourront �tre d�riv�es des syst�mes Berkeley BSD licenci�s par l'Universit� de Californie. Sun, Sun Microsystems, le logo Sun, Java et Solaris sont des marques de fabrique ou des marques d�pos�es de Sun Microsystems, Inc. aux Etats-Unis et dans d'autres pays. Toutes les marques SPARC sont utilis�es sous licence et sont des marques de fabrique ou des marques d�pos�es de SPARC International, Inc. aux Etats-Unis et dans d'autres pays.