Sun ONE logo     Previous      Contents      Index      Next     
Sun ONE Application Server 7 Administrator's Guide



Configuring the Web Server Plugin

This module explains how Sun ONE Application Server processes HyperText Transfer Protocol (HTTP) requests, and how to configure and use the web server plugin with Sun ONE Application Server. This chapter also explains how to configure and use the web server plugin with Microsoft IIS.

This module includes the following topics:

About the Web Server Plugin

The web server plugin is an HTTP reverse proxy plugin that allows you to instruct a Sun ONE Web Server or Sun ONE Application Server to forward certain HTTP requests to another server. For example, you can configure a web server connected to the Internet to forward requests for specific web applications to an application server located behind a corporate firewall.

Within Sun ONE Application Server, the web server plugin allows one server instance to forward an HTTP (web) request to another server instance.

The web server plugin performs the following functions:

  • Re-uses connections from the proxy server, whenever possible. This eradicates the necessity of opening new connections to process incoming requests.
  • The web server plugin starts streaming requests and responses as it starts receiving them. In other words, the plugin does not wait till the request or response is collected fully before forwarding it to the remote server.
  • The web server plugin maintains multiple outbound HTTP connections to the same remote server, as appropriate. Connections formed for requests that are forwarded by the web server plugin are called outbound HTTP connections.

To understand how the web server plugin works, it is necessary to understand the basics of HTTP requests, and specifically the method used by Sun ONE Application Server to process HTTP requests.

Handling Client Requests

Sun ONE Application Server is an application server that can directly accept and respond to HTTP requests. In this section, we will discuss HTTP basics in and also look at how Sun ONE Application Server handles requests. This section covers the following topics:

HTTP Basics

As a quick summary, the HTTP/1.1 protocol works as follows:

  • The client (usually a browser) opens a connection to the server and sends a request
  • The server processes the request, generates a response, and closes the connection if it finds a Connection: Close header.

The request consists of a line indicating a method such as GET or POST, a Universal Resource Identifier (URI) indicating which resource is being requested, and an HTTP protocol version separated by spaces.

This is normally followed by a number of headers, a blank line indicating the end of the headers, and sometimes body data. Headers may provide various information about the request or the client body data. Headers are typically only sent for POST and PUT methods.

The example request shown below would be sent by a browser to request the server foo.com to send back the resource in /index.html. In this example, no body data is sent because the method is GET (the point of the request is to get some data, not to send it.)


GET /index.html HTTP/1.0

User-agent: Mozilla

Accept: text/html, text/plain, image/jpeg, image/gif, */*

Host: foo.com


The server receives the request and processes it. It handles each request individually, although it may process many requests simultaneously. Each request is broken down into a series of steps that together make up the request handling process.

The server generates a response which includes the HTTP protocol version, HTTP status code, and a reason phrase separated by spaces. This is normally followed by a number of headers. The end of the headers is indicated by a blank line. The body data of the response follows. A typical HTTP response might look like this:


HTTP/1.0 200 OK
Server: Standard/7.0
Content-type: text/html
Content-length: 83

<HTML>
<HEAD><TITLE>Hello World</Title></HEAD>
<BODY>Hello World</BODY>
</HTML>

The status code and reason phrase tell the client how the server handled the request. Normally the status code 200 is returned indicating that the request was handled successfully and the body data contains the requested item. Other result codes indicate redirection to another server or the browser's cache, or various types of HTTP errors such as "404 Not Found."

Steps in the Request Handling Process

When Sun ONE Application Server first starts up it performs certain initialization tasks, and then waits for an HTTP request from a client (such as a browser). When it receives a request, it first selects a virtual server.

After the virtual server is selected, the virtual server's obj.conf file specifies how the request is handled with the following steps:

  1. AuthTrans (authorization translation)
  2. Verify any authorization information (such as name and password) sent in the request.

  3. NameTrans (name translation)
  4. Translate the logical URI into a local file system path.

  5. PathCheck (path checking)
  6. Check the local file system path for validity and check that the requestor has access privileges to the requested resource on the file system.

  7. ObjectType (object typing)
  8. Determine the MIME-type (Multi-purpose Internet Mail Encoding) of the requested resource (for example. text/html, image/gif, and so on).

  9. Service (generate the response)
  10. Generate and return the response to the client.

  11. AddLog (adding log entries)
  12. Add entries to log file(s).

  13. Error (service)
  14. This step is executed only if an error occurs in the previous steps. If an error occurs, the server logs an error message and aborts the process.

Web Server Plugin Configuration

The configuration and behavior of the web server plugin are determined by a set of configuration files. Sun ONE Application Server looks at the configuration defined in these files each time it processes a request from a client. The configuration files are named obj.conf and init.conf. The obj.conf file is prefixed with the name of the virtual server, for example server1-obj.conf. For more information, see "The obj.conf File".

Each instance of Sun ONE Application Server has its own init.conf file, to which the server refers at startup.

As discussed in the preceding topic, the obj.conf configuration file contains a series of instructions (directives) that tell Sun ONE Application Server what to do at each stage in the client request and response process. Each directive invokes a Server Application Function (SAF).

The obj.conf file is essential to the operation of the Sun ONE Application Server. When you make changes to the server through the Administration interface, the system automatically updates obj.conf.

The init.conf configuration file sets values of variables that configure the server during initialization. The server executes the configuration parameters specified in this file, during server start up. See the Sun ONE Application Server Administrator's Configuration File Reference for more information.

The following figure illustrates the relationship between the web browser, a front-end web server, a backend application server, and the web server plugin's service-passthrough and auth-passthrough SAFs:

   Relationship Between Web Browser, Web Server, Application Server, and Web Server Plugin SAFs
Figure shows the relationship between the web browser, a front-end web server, a backend application server, and the web server plugin's service-passthrough and auth-passthrough SAFs.

The Web Server Plugin SAF Reference

This section discusses the function and behavior of the following Server Application Functions (SAF):

init-passthrough

The init-passthrough function initializes the web server plugin. This function must be called before the web server plugin can be used.

Example:

Init fn="load-modules" shlib="c:/plugins/passthrough.dll" funcs="init-passthrough,auth-passthrough,check-passthrough,service- passthrough" NativeThread="no"

Init fn="init-passthrough"

auth-passthrough

The auth-passthrough SAF is applicable in AuthTrans-class directives.

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

  • IP address request originated from
  • SSL key size used by originating client
  • SSL client certificate presented by originating client

When auth-passthrough detects encoded client information, it treats the request as a direct request from the originating client and not as a request forwarded by an intermediate server running service-passthrough.

Since auth-passthrough makes it possible to override information that may be used for authentication (for example, the IP address from which the request originated) it is important that only trusted clients or servers be allowed to connect to a server running auth-passthrough. As a precautionary measure, it is recommended that only servers behind the corporate firewall should run auth-passthrough. A server that is accessible through the Internet should not run the auth-passthrough SAF. The auth-passthrough SAF should be used only if the relevant information about the originating client is required.

Example:

AuthTrans fn="auth-passthrough"

service-passthrough

The service-passthrough SAF is applicable in Service-class directives.

The service-passthrough SAF forwards a request from one server to another server for processing. The service-passthrough SAF can be configured to use SSL or non SSL (HTTPS or HTTP) connections to the remote server, independent of the type of connection through which the original request was received. The service-passthrough SAF encodes information about the originating client that may be decoded by an auth-passthrough function running on the remote server.

A service-passthrough directive is typically used in combination with other directives in the obj.conf configuration file as follows:

<Object name="passthrough">

ObjectType fn="force-type" type="magnus-internal/passthrough"

Error reason="Bad Gateway" fn="send-error" uri="$docroot/badgateway.html"

</Object>

<Object name="default">

....

NameTrans fn="assign-name" from="(/webapp1|/webapp1/*)" name="passthrough"

...

</Object>

If the backend application server is down, the user will be shown the local HTML file badgateway.html instead. In case the server running the service-passthrough SAF needs to serve files to which it has access, and forward only rejected requests to the backend application servers, the ObjectType line would be changed to:

ObjectType fn="check-passthrough" type="magnus-internal/passthrough"

check-passthrough

The check-passthrough SAF is Applicable in ObjectType-class directives.

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

Parameters:

type - (optional) type to set when the request resource does not exist. The default is "magnus-internal/passthrough".

Example

ObjectType fn="check-passthrough"

Using the Web Server Plugin

To add the plugin to Sun ONE Web Server or a Sun ONE Application Server instance, follow these steps:

  1. Make sure the libpassthrough.so (UNIX) or passthrough.dll (Windows) file is in the install_dir/plugins/passthrough/bin directory. When adding the plugin to Sun ONE Web Server 6.0, you must copy the plugin from an Sun ONE Application Server 7 installation.
  2. Add the following lines to the install_dir/config/init.conf (for Sun ONE Application Server 7) or install_dir/config/magnus.conf (for Sun ONE Web Server 6.0) configuration file. Each line begins with Init and is all on one line.
  3. Windows:

    Init fn="load-modules" shlib="c:/install_dir/plugins/passthrough/bin/passthrough.dll" funcs="init-passthrough,auth-passthrough,check-passthrough,service-passthrough" NativeThread="no"

    Init fn="init-passthrough"

    UNIX:

    Init fn="load-modules" shlib="install_dir/plugins/passthrough/bin/libpassthrough.so" funcs="init-passthrough,auth-passthrough,check-passthrough,service-passthrough" NativeThread="no"

    Init fn="init-passthrough"

  4. Add a passthrough <Object> to obj.conf by adding the following lines to the top of the config/appserver-server-instance-obj.conf configuration file. On Sun ONE Application Server, the step must be performed on the config/<appserver-server-instance>-obj.conf file
  5. <Object name="passthrough">
    ObjectType fn="force-type" type="magnus-internal/passthrough"
    Service type="magnus-internal/passthrough" fn="service-passthrough" servers="
    server"
    Error reason="Bad Gateway" fn="send-error" uri="$docroot/badgateway.html"
    </Object>

    where server is a URL of the following form:

    http://servername:port

  6. Configure which URIs are to be forwarded by adding lines such as the following to the top of the default object in the install_dir/config/obj.conf configuration file:
  7. NameTrans fn="assign-name" from="(/uri|/uri/*)" name="passthrough"

    The uri is the context root of a web application deployed on the remote servers, and passthrough corresponds to the name of the <Object> in obj.conf, as given in Step 3.

    For example:

    <Object name="default">
    ...
    NameTrans fn="assign-name" from="(/webapp1|/webapp1/*)" name="passthrough"
    ...
    </Object>

  8. Restart the server.


  9. Note

    For Solaris and Linux, the name of the plugin library will be libpassthrough.so. For Windows, the name of the plugin library will be passthrough.dll



Configuring Microsoft IIS To Use the Web Server Plugin

Configuring the Microsoft Internet Information Services to use the web server plugin involves configuring the web server plugin for use with Microsoft IIS, and configuring Microsoft IIS to use the web server plugin.

You can also configure server pools to handle multiple applications that run on different servers.

The following topics are covered in this section:

Configuring the Web Server Plugin for IIS

To configure the web server plugin for IIS, perform the following tasks:

  1. Create a directory for the web server plugin under the under the IIS wwwroot directory, by typing the following command, from the C:\ command line prompt:
  2. md \Inetpub\wwwroot\sun-passthrough

  3. Copy the plugin files to the C:\Inetpub\wwwroot\sun-passthrough directory.
  4. Use a text editor to add the URL of the machine on which Sun ONE Application Server is installed, to the C:\Inetpub\wwwroot\sun-passthrough\sun-passthrough.properties file.
  5. You will need to add the following information via a text editor:

    server=http://appservername:port

    where, appservername is the hostname or IP address of machine on which Sun ONE Application Server is installed, and port is the number of the port on which it listens (this value is typically set to 80).

  6. List the context roots you want Sun ONE Application Server to service in the C:\Inetpub\wwwroot\sun-passthrough\sun-passthrough.properties file.
  7. These context roots should correspond to the context roots of applications deployed on Sun ONE Application Server. Requests to these context roots will be serviced by Sun ONE Application Server, while other requests are handled by the IIS web server. The command lines to pass requests to a web application is:

    passthrough=/webapplication

    where, /webapplication is the context root of a web application. To pass all requests to Sun ONE Application Server, add the following line:

    passthrough=/

You have now configured the web server plugin in the Microsoft IIS root directory. To complete the process, you now need to configure Microsoft IIS to use the web server plugin.

Configuring IIS to Use the Web Server Plugin

To configure IIS to use the web server plugin, you need to open the Windows Internet Services Manager. The Internet Services Manager is located in the Administrative Tools folder in the Control Panel folder.

Open the Internet Services Manager, and perform the following tasks:

  1. Select the web site for which you want to enable the plugin. This web site is typically named the Default Web Site.
  2. Right click on the web site and select Properties to open the Properties notebook.
  3. Open the ISAPI Filters tab, click the Add button, and follow the steps given below, to add a new ISAPI filter:
    1. In the Filter Name field, enter Sun ONE Application Server
    2. In the Executable field, type C:\Inetpub\wwwroot\sun-passthrough\sun-passthrough.dll
    3. Click OK, and close the Properties notebook.

  4. You now need to create and configure a new virtual directory. Follow the steps given below to create and configure a new virtual directory:
    1. Right click on the default web site, select New, and then Virtual Directory. The Virtual Directory Creation Wizard opens.
    2. In the Alias field, type sun-passthrough.
    3. In the Directory field, type C:\Inetpub\wwwroot\sun-passthrough
    4. Ensure that you check the Execute Permission checkbox and that all other permission checkboxes are left unchecked.
    5. Click Finish.

  5. You need to stop and start the web server, for your new settings to take effect. To stop the web server, right click on the web site and select Stop. To start the web server, right click on the web site and select Start.
  6. Next, type the following in a web browser, to access the web application context root:

    http://webservername/webapplication

    where, webservername is the hostname or IP address of the web server and /webapplication is the context root that you listed in the C:\Inetpub\wwwroot\sun-passthrough\sun-passthrough.properties file to verify that the web server, web server plugin, and Sun ONE Application Server are operating correctly.

Configuring Multiple Server Pools

It is possible to partition your web applications across multiple application servers (that is, you run some applications on one set of servers and other applications on another set of servers) by configuring server pools in the sun-passthrough.properties file. For each server pool, choose a unique name, comprised of letters and numbers. Once you complete the steps for installing and configuring the web server plugin for Microsoft IIS, as given in the section "Configuring Microsoft IIS To Use the Web Server Plugin", edit the C:\Inetpub\wwwroot\sun-passthrough\sun-passthrough.properties file and prefix the relevant server and passthrough property lines with the unique name that you choose for the server pool. Place a period (.) after the server pool name.

For example, the following lines from the sun-passthrough.properties file define two server pools. The first server pool consists of server-a and the services requests for context root /app1. The second server pool consists of server-b and the services requests for /app2 and /app3 context roots.

server=http://server-a

passthrough=/app1

serverpool2.server=http://server-b

serverpool2.passthrough=/app2

serverpool2.passthrough=/app

Sample sun-passthrough.properties File

# Sun ONE Application Server web server plugin for IIS

#

# This file is used to configure the Sun ONE Application Server web server

# plugin for IIS. Lines beginning with a '#' are ignored.

# server

#

# The server property specifies the URL of an application server. If multiple

# server properties are given, the plugin will distribute load across the

# specified application servers.

#

server=http://localhost:8080

# passthrough

#

# The passthrough property specifies the context root (virtual directory) of a

# web application. Requests for the given context root will be passed to the

# application server for processing. If 'passthrough=/' is specified, all

# requests will be passed to the application server for processing.

#

# passthrough properties should be ordered from most to least specific. For

# example, 'passthrough=/apps/app1' should appear before 'passthrough=/apps'.

#

# Multiple passthrough properties are allowed.

#

#passthrough=/webapp

#passthrough=/servlets

#passthrough=*.jsp

passthrough=/

# prefix

#

# The prefix property specifies the IIS virtual directory that contains the

# plugin DLL, sun-passthrough.dll.

#

prefix=/sun-passthrough

# error-url

#

# The error-url property specifies the URL of a page to redirect the client to

# when the application server is unavailable.

#

#error-url=/badgateway.htm

# It is possible to configure multiple server pools by prefixing the server

# and passthrough property names with a pool name followed by a period ('.').

# Pool names can be any sequence of letters and numbers.

#

# For example, the following properties define two server pools. One server

# pool will service the web applications at '/app1' and the other will service

# the web applications at '/app2' and '/app3':

#

#serverpool1.server=http://server-a

#serverpool1.passthrough=/app1

#

#serverpool2.server=http://server-b

#serverpool2.passthrough=/app2

#serverpool2.passthrough=/app3


Previous      Contents      Index      Next     
Copyright 2002 Sun Microsystems, Inc. All rights reserved.