Chapter 7
Configuring the Web Server Plugin

This chapter 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, and the Apache web server.

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

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:

AuthTrans (authorization translation)

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

NameTrans (name translation)

Translate the logical URI into a local file system path.

PathCheck (path checking)

Check the local file system path for validity and check that the requestor has access privileges to the requested resource on the file system.

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:

auth-passthrough

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.

This is useful in two-tier deployment scenarios where;

a Sun ONE Application Server instance is hidden by a second firewall behind the corporate firewall

no client connections are permitted directly to the S1AS instance.

In such network architectures, a client always connects to the front-end web server which is running the proxy plugin. This web server is the one that forwards requests to Sun ONE Application Server. This indicates that Sun ONE Application Server can only receive requests from the proxy host (in this case, the web server), and never directly from client hosts. This means that if applications, deployed on a Sun ONE Application Server instance that is behind two firewalls, query for client information such as the client’s IP address, the applications will get the proxy host IP (since that is the actual originating host for the relayed request). The auth-passthrough SAF can be used to modify this behavior so that the remote (proxied) client information is presented instead.

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.

Note that in the scenario described above, SSL client authentication could be turned 'on' only for web server and turned 'off' always for application server, for the configuration to work properly.

Command Example:

AuthTrans fn="auth-passthrough"

service-passthrough

The service-passthroughSAF 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:

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 use the web server plugin on a Sun ONE Web Server, you must make changes to the configuration files of both Sun ONE Application Server and Sun ONE Web Server. Follow the procedures listed in this section to configure and use the Sun ONE Web Server plugin:

This completes the changes you need to make to Sun ONE Application Server. The procedures in the preceding section is to configure a single instance of the application server. To enable more instances to use the web server plugin, you must make these changes in the configuration files of those application server instances.

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.

Configuring the Web Server Plugin for IIS

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

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:

md \Inetpub\wwwroot\sun-passthrough

Copy the plugin files to the C:\Inetpub\wwwroot\sun-passthrough directory.

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.

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

List the context roots you want Sun ONE Application Server to service in the C:\Inetpub\wwwroot\sun-passthrough\sun-passthrough.properties file.

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:

Select the web site for which you want to enable the plugin. This web site is typically named the Default Web Site.

Right click on the web site and select Properties to open the Properties notebook.

Open the ISAPI Filters tab, click the Add button, and follow the steps given below, to add a new ISAPI filter:

In the Filter Name field, enter Sun ONE Application Server

In the Executable field, type C:\Inetpub\wwwroot\sun-passthrough\sun-passthrough.dll

Click OK, and close the Properties notebook.

You now need to create and configure a new virtual directory. Follow the steps given below to create and configure a new virtual directory:

Right click on the default web site, select New, and then Virtual Directory. The Virtual Directory Creation Wizard opens.

In the Alias field, type sun-passthrough.

In the Directory field, type C:\Inetpub\wwwroot\sun-passthrough

Ensure that you check the Execute Permission checkbox and that all other permission checkboxes are left unchecked.

Click Finish.

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.

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

Compiling Apache With mod_proxy Module

Unpack the source distribution. The source distribution comes as a compressed archive. If you are installing Apache 1.3.27, the source distribution archive will read apache_1.3.27.tar.gz.

De-compress and untar the archive using the following command:

$ tar -zxvf apache_1.3.27.tar.gz

This command will create a directory called apache_1.3.27 in your current working directory.

You now need to configure your environment to compile the Apache source code. The source distribution comes with a script called configure, which checks your environment for the necessary support files (such as headers, shared libraries and utility programs) that are required to successfully compile Apache.

To configure you environment, go to the Apache source directory and proceed with the following steps:

Make sure that the following paths exist, while installing Apache on Solaris:

CC=/opt/SUNWspro/bin/cc

Where /opt/SUNWspro/bin is the path where cc is installed. Make sure that this is in your PATH.

Make sure that /usr/ccs/bin is in your PATH.

Run the following command:

./configure --enable-module=proxy --prefix=/usr/local/apache

The path specified in the prefix argument indicates where you wish to install Apache.This is a variable and you can specify the path where you want to install Apache.

This command will output several lines on the screen.Essentially this command creates the Makefiles for the build according to your system configuration. If there are errors in configure, you may be missing some header files or utility programs which you must install before proceeding.

After the configure script runs successfully, you can compile Apache using the make command, as follows:

make

This command will output several lines on the screen indicating that the process is compiling Apache source code and linking Apache. This process should normally conclude without errors. However if any errors occur, please check if all the library files and utility programs of Apache have been properly downloaded.

You now need to install Apache. Apache installs itself in the /usr/local/apache directory (or any other directory that you specify). To install Apache, run the following command:

make install

If this command executes successfully, your system now has Apache installed. You should see Apache's installation files in the following directory:

/usr/local/apache

The main configuration file, called httpd.conf, will be installed in the /usr/local/apache/conf directory.

Note

mod_proxy lacks the SSL transport and load balancing features of Sun ONE Application Server 7 reverse proxy plugin. Also, it is not possible for web applications to obtain the client’s IP address or SSL client certificate when using mod_proxy.

Modifying the httpd.conf File

Apache is configured through the file, httpd.conf. This file consists of a number of Apache directives, which determine the various operating parameters of the Apache server. For a simple installation of Apache, you will need to modify the following few directives:

ServerRoot “/usr/local/apache”Port 5000

ServerRoot is the path in which you installed Apache.

Apache is now configured for default behavior and web serving. Next, you must add the following application server specific directives to the httpd.conf file to enable Apache to forward HTTP requests to Sun ONE Application Server:

Here, <s1as_server.some.domain>:<port> should be replaced by the URL address of your Sun ONE Application Server. Duplicate these two lines for each web application context root, where /application is the web application context root and http://server is the URL of the Sun ONE Application Server.

This completes your configuration of Apache web server.

Starting And Stopping Apache

Apache comes bundled with a script titled apachectl that facilitates starting, stopping and restarting Apache. Run the follow command to start Apache

$ /usr/local/apache/bin/apachectl start

To stop apache, run the following command:

use /usr/local/apache/bin/apachectl stop

After you start, you can test your installation of Apache. Once Apache is running, type the following address in your web browser: http://localhost/. If your installation was successful and Apache is running, you should see a test page displaying a message to the effect.