Sun Java System Web Server 6.1 SP12 Reverse Proxy Plug-in Release Notes

Release Notes for Sun JavaTM System Web Server 6.1 Reverse Proxy Plug-in

These release notes contain important information available at the time of release of Sun Java System Web Server 6.1 Reverse Proxy plug-in, 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.

In addition to the 32–bit platform support, Sun Java System Web Server 6.1 SP12 also provides support to 64–bit Reverse Proxy.

The Sun Java System Web Server 6.1 SP12 manuals are available as online files in PDF and HTML formats at: http://docs.sun.com/app/docs/coll/1308.9

These release notes contain the following sections:

Introduction

The Reverse Proxy Plug-in is a NSAPI plug-in designed for use with the Sun Java System Web Server 6.1 SP12 and later Service packs. Same functionality is now provided by 64-bit Reverse Proxy Plug-in (Solaris SPARC Only) which can be used with Sun Java System Web Server 6.1 SP12 and later Service packs.

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. Reverse proxy provides additional layer of protection between the public Internet and the origin servers. Web Server can be configured as Reverse Proxy server for any back end application servers.

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

The Reverse Proxy plug-in includes support for the following features:

HTTP/1.0 and HTTP/1.1 Compliance

The Reverse Proxy plug-in issues 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 plug-in passes through basic-auth and digest-auth credentials presented by the client. It encodes 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 plug-in can be configured to present its own credentials to an origin server. The Reverse Proxy plug-in is capable of presenting basic-auth or utilizing a specified certificate nickname.

Data Encryption

The Reverse Proxy plug-in can utilize SSLv2, SSLv3 and TLS when making requests to origin servers.

Session Stickiness

The Reverse Proxy plug-in can be configured to recognize sticky cookies, and can have the name of the sticky cookies be configured.

Simple Load Balancing

The Reverse Proxy plug-in distributes load to several configured origin servers.

Granular Error Logging

The Reverse Proxy plug-in takes advantage of the Web Server's granular error logging capabilities such as config, failure, warning, fine, finer, and finest. See the Web Server documentation at for more detail.

Server Application Functions (SAFs)

The Reverse Proxy plug-in 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 through 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.

Because 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 information about the originating client is not required, auth-passthrough should not be used.

The following obj.conf code 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.

<Object name="passthrough">
ObjectType fn="force-type" type="magnus-internal/passthrough"
Service type="magnus-internal/passthrough" fn="service-passthrough"
servers="http://xxx:8084/" poll-timeout="18000" retries="0"
Error reason="Bad Gateway" fn="send-error"
uri="/opt/iplanet/web41sp8/docs/badgateway.html"
</Object>

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 –

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.

Resolved Issues

The following table lists the issues resolved in Sun Java System Web Server 6.1 Reverse Proxy plug-in.

Table 1 Issues Resolved in Sun Java System Web Server 6.1 Reverse Proxy Plug-In

Problem ID 

Description 

6435723 

High CPU usage in Reverse Proxy Plug-in. 

6482816 

Web Server Reverse Proxy Plug-in replaces commas in a cookie header with semicolons. 

6571031 

Reverse Proxy Plugin should abort processing after the client write()fails with EPIPE.

Installing the Reverse Proxy plug-in

The Reverse Proxy plug-in is available for use with the Sun Java System Web Server 6.1 SP11 or later Service Packs.

The 64-bit Reverse Proxy Plug-in (Solaris SPARC only) is available for use with the Sun Java System Web Server 6.1 SP11 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  

Installing on Windows


$ unzip sun-webserver61-passthrough-win.zip

;; Uncompress the ZIP archive

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 installation places the shared object and README in: /opt/SUNWwbsvr/plug-ins/passthrough


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 installation places the shared object and README in /opt/sun/webserver/plug-ins/passthrough


Configuring the Reverse Proxy plug-in

The Reverse Proxy plug-in should be initialized in the Sun 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 is 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” is 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 plug-in provides its own credentials through 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 plug-in, contact Sun customer support using one of the following mechanisms:

Please have the following information available prior to contacting support. This helps to ensure that our support staff can best assist you in resolving problems.

Sun Welcomes Your Comments

Sun is interested in improving its documentation and welcomes your comments and suggestions. To share your comments, go to http://docs.sun.com and click Feedback.

Additional Sun Resources

Useful Sun Java System information can be found at the following locations: