Previous Contents Index Next |
Sun Java System Application Server Standard and Enterprise Edition 7 2004Q2 Administration Guide

> ## Chapter 12
> Configuring the Web Server Plug-in

> This chapter explains how Sun Java™ System Application Server Standard Edition 7 processes HyperText Transfer Protocol (HTTP) requests, and how to configure and use the web server plug-in with the Application Server. This chapter also explains how to configure and use the web server plug-in with Microsoft IIS, and Apache web server.

> Note | The procedures documented in this chapter apply only to Sun Java System Application Server 7, Standard Edition web server plug-in. This plug-in does not provide HTTP session failover capabilities. HTTP load balancing and failover is available in the enterprise edition and is described in Chapter 17, "Configuring HTTP Load Balancing and Failover (Enterprise Edition)."

> This chapter includes the following topics:

> - About the Web Server Plug-in
> - Handling Client Requests
> - Web Server Plug-in Configuration
> - Web Server Plug-in SAF Reference
> - Using The Web Server Plug-in

> ##

> About the Web Server Plug-in

> The web server plug-in is an HTTP reverse proxy plug-in that allows you to instruct a Sun Java System Web Server or the 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.

> WithinSun Java SystemApplication Server, the web server plug-in allows one server instance to forward an HTTP (web) request to another server instance.

> The web server plug-in 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 plug-in starts streaming requests and responses as it starts receiving them. In other words, the plug-in does not wait till the request or response is collected fully before forwarding it to the remote server.
> - The web server plug-in maintains multiple outbound HTTP connections to the same remote server, as appropriate. Connections formed for requests that are forwarded by the web server plug-in are called outbound HTTP connections.

> To understand how the web server plug-in works, it is necessary to understand the basics of HTTP requests, and specifically the method used bySun Java SystemApplication Server to process HTTP requests.

> ##

> Handling Client Requests

> In this section, we will discuss HTTP basics in and also look at how Sun Java System Application Server handles requests. This section covers the following topics:

> - HTTP Basics
> - Steps in the Request Handling Process

> ### 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

> WhenSun Java SystemApplication 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)

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

> 2. NameTrans (name translation)

> Translate the logical URI into a local file system path.

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

> 4. ObjectType (object typing)

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

> 5. Service (generate the response)

> Generate and return the response to the client.

> 6. AddLog (adding log entries)

> Add entries to log file(s).

> 7. Error (service)

> 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 Plug-in Configuration

> The configuration and behavior of the web server plug-in are determined by a set of configuration files. 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 obj.conf File.

> Each instance ofSun Java SystemApplication 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 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 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 Java System 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 plug-in's service-passthrough and auth-passthrough SAFs:

> Figure 12-1 Relationship Between Web Browser, Web Server, Application Server, and Web Server Plug-in SAFs

> ##

> Web Server Plug-in SAF Reference

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

> - init-passthrough
> - auth-passthrough
> - service-passthrough
> - check-passthrough

> ### init-passthrough

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

> Example:

> Init fn="load-modules" shlib="c:/plugins/passthrough.dll" funcs="init-passthrough,auth-passthrough,check-passthrough,service-passthr ough" 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.

> This is useful in two-tier deployment scenarios where:

> - a Sun Java System 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 plug-in. This web server is the one that forwards requests to Application Server. This indicates that 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 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, the Application Server’s obj.conf and init.conf configuration files must be suitably modified, as described in Changes to Sun Java System Application Server.

> ### 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 Plug-in

> To use the web server plug-in as a proxy to Sun Java System Application Server, you must make changes to the configuration files of both the Application Server and Web Server. Follow the procedures listed in this section to configure and use the Reverse Proxy Plug-in.

> - Configuring Sun Java System Web Server
> - Configuring Application Server as a Proxy
> - Configuring Microsoft IIS
> - Configuring Apache Web Server

> ### Configuring Sun Java System Web Server

> To configure Sun Java System Web Server as a proxy, you need to make changes to both Web Server and Application Server configuration files. These changes are described in the following sections:

> - Changes to Sun Java System Web Server
> - Changes to Sun Java System Application Server

> ### Changes to Sun Java System Web Server

> Take backups of critical configuration files, such as magnus.conf and obj.conf, before making changes to these files.

> 1. Create a directory in the web server installation area that will contain the passthrough plug-in. For example:

> cd /webserver_install_dir/plugins

> mkdir -p passthrough/bin

> 2. Copy the passthrough plug-in from Sun Java System Application Server installation to this new, web server directory. For example:

> cd appserver_install_dir/lib/webserver-plugin/platform/web_server/

> cp libpassthrough.so webserver_install_dir/plugins/passthrough/bin

> On Windows, copy the passthrough.dll file.

> 3. Create a directory, lbplugin/resource, under web_server_install_dir/plugins.
> 4. Copy all *.res files from appserver_install_dir/lib/webserver-plugin/platform/web_server to web_server_install_dir/plugins/lbplugin/resource.
> 5. Edit the magnus.conf file, found under webserver_install_dir/https-host.domain/config, and append the following lines:

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

> 6. Edit the obj.conf file, found under webserver_install_dir/https-host.domain/config, and add the NameTrans directive as shown:

> <Object name=”default”>
> NameTrans fn="assign-name" from="/*" name="passthrough"
> ...
> </Object>

> The from="/*" 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.

> For example:

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

> 7. Add the following lines in the obj.conf file:

> <Object name="passthrough">
> ObjectType fn="force-type" type="magnus-internal/passthrough"
> PathCheck fn="deny-existence" path="*/WEB-INF/*"
> Service type="magnus-internal/passthrough" fn="service-passthrough"
> servers="http://servername:port"
> Error reason="Bad Gateway" fn="send-error" uri="$docroot/badgateway.html"
> </Object>

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

> 8. Include the path of plug-in file to the PATH variable.
> 9. Restart the Sun Java System Web Server instance.

> Next, you must configure Sun Java System Application Server to receive SSL requests from the web server plug-in.

> Note | Ensure that the KeepAliveTimeout value is the same in both the web server’s magnus.conf file and the Application Server’s init.conf file. If the values are different, the connection might get closed prematurely, either by the web server or Application Server, and you will see a 502 error in the browser.

> ### Changes to Sun Java System Application Server

> Take backups of the critical configuration files, such as init.conf, and server1-obj.conf, before making changes to these files. Server1 is the name of the Application Server that you are about to configure.

> 1. Edit the install_dir/domains/domain1/server1/config/init.conf file and append the following lines:

> On UNIX:

> Init fn="load-modules" shlib="appserver_install_dir/lib/webserver-plugin/platform/web_server/libpassthrough.s o"
> funcs="init-passthrough,auth-passthrough,check-passthrough,service-passthr ough" NativeThread="no"
> Init fn="init-passthrough"

> On Windows:

> Init fn="load-modules"
> shlib="c:/appserver_install_dir/lib/webserver-plugin/platform/web_server/libpassthroug h.dll"
> funcs="init-passthrough,auth-passthrough,check-passthrough, service-passthrough" NativeThread="no"
> Init fn="init-passthrough"

> 2. Edit the install_dir/domains/domain1/server1/config/server1-obj.conf and add the AuthTrans directive as shown here:

> <Object name="default">
> AuthTrans fn="match-browser" browser="*MSIE*" ssl-unclean-shutdown="true" AuthTrans fn="auth-passthrough"
> </Object>

> 3. Append the bin PATH of the Application Server with the path of the plug-in.
> 4. Restart the Sun Java System Application Server instance.

> This completes the changes you need to make to Sun Java System 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 plug-in, you must make these changes in the configuration files of those Application Server instances.

> Note | For Solaris and Linux, the name of the plug-in library will be libpassthrough.so. For Windows, the name of the plug-in library will be passthrough.dll. However, for Microsoft IIS, the plug-in is named as sun-passthrough.dll.. The value of keepAliveTimout should be the same in both the web server’s magnus.conf file and the Application Server’s init.conf file. If these values are different, the connection between the Application Server and web server may be closed prematurely, and 502 error messages will be printed in the server.log log file.

> ### Configuring Application Server as a Proxy

> Follow these instructions to configure Application Server to act as a proxy to another Application Server or web server. Make sure to take backups of critical configuration files, such as magnus.conf, init.conf, and server1-obj.conf, before making changes to these files.

> 1. Create a directory, plugins/lbplugin/resource, under appserver_install_dir/domains/domain1/server1.
> 2. Copy all *.res files from appserver_install_dir/lib/webserver-plugin/platform/iws61 to appserver_install_dir/domains/domain1/server1/plugins/lbplugin/resource.
> 3. Edit the magnus.conf file, found under appserver_install_dir/https-host.domain/config, and append the following lines:

> Init fn="load-modules" shlib="appserver_install_dir/lib/webserver-plugin/platform/iws61/libpassthrough.so" funcs="init-passthrough,auth-passthrough,check-passthrough,service-passthr ough" NativeThread="no"
> Init fn="init-passthrough"

> 4. Edit the server1-obj.conf file, found under appserver_install_dir/https-host.domain/config, and add the NameTrans directive as shown:

> <Object name=”default”>
> NameTrans fn="assign-name" from="/*" name="passthrough"
> ...
> </Object>

> The from="/*" 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.

> For example:

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

> 5. Add the following lines in the obj.conf file:

> <Object name="passthrough">
> ObjectType fn="force-type" type="magnus-internal/passthrough"
> PathCheck fn="deny-existence" path="*/WEB-INF/*"
> Service type="magnus-internal/passthrough" fn="service-passthrough"
> servers="http://servername:port"
> Error reason="Bad Gateway" fn="send-error" uri="$docroot/badgateway.html"
> </Object>

> servername is the hostname or IP address of the machine to which the proxy plug-in must route HTTP/S requests to, and port is the number of the port on which the server listens (this value is typically set to 80).

> 6. Include the path of the plug-in file in the PATH environment variable.
> 7. To enable these changes, use the following command to reconfigure the Application Server instance.

> asadmin reconfig --user admin --password password --port 4848 --keepmanualchanges server1

> 8. Restart the Sun Java System Application Server instance.

> ### Configuring Microsoft IIS

> Configuring the Microsoft Internet Information Services to use the web server plug-in involves configuring the web server plug-in for use with Microsoft IIS, and configuring Microsoft IIS to use the web server plug-in.

> 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 Plug-in for IIS
> - Configuring IIS to Use the Web Server Plug-in
> - Configuring Multiple Server Pools
> - Sample sun-passthrough.properties File

> ### Configuring the Web Server Plug-in for IIS

> To configure the web server plug-in for IIS, perform the following tasks:

> 1. Create a directory for the web server plug-in under the under the IIS wwwroot directory, by typing the following command, from the C:\ command line prompt:

> md \Inetpub\wwwroot\sun-passthrough

> 2. Copy the plug-in files from the product CD to the C:\Inetpub\wwwroot\sun-passthrough directory.

> By default, the plug-in files, after unzipping, will be located in:

> appserver_install_dir\lib\webserver-plugin\windows\iis\

> 3. Create a directory, lbplugin\resource, under web_server_install_dir\sun-passthrough.
> 4. Copy all *.res files from appserver_install_dir\lib\webserver-plugin\windows\iis to web_server_install_dir\sun-passthrough\lbplugin\resource.
> 5. Copy the sun-passthrough.properties file from appserver_install_dir\lib\webserver-plugin\windows\iis to web_server_install_dir\sun-passthrough.
> 6. Use a text editor to add the URL of the machine (on which Sun Java System Application Server is installed), to the C:\Inetpub\wwwroot\sun-passthrough\sun-passthrough.properties file.

> server=http://appservername:port

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

> 7. List the context roots you want 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 Application Server. Requests to these context roots will be serviced by 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 Application Server, add the following line:

> passthrough=/

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

> ### Configuring IIS to Use the Web Server Plug-in

> To configure IIS to use the web server plug-in, 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 plug-in. 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 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. Add the path of sun-passthrough.dll file to the PATH environment variable of the bin path of Application Server.
> 6. 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 plug-in, and 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 plug-in for Microsoft IIS, as given in the section Configuring Microsoft IIS, edit the C:\Inetpub\wwwroot\plugins\lbplugins\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 Java System Application Server web server plugin for IIS

> #

> # This file is used to configure the Sun Java System 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

> ### Configuring Apache Web Server

> This section describes how you can compile the Apache source code and configure your installation of Apache Web Server to work with Sun Java System Application Server.

> To enable HTTP requests to be sent to Sun Java System Application Server, you must compile the Apache sources to use the mod_proxy module, and then modify the httpd.conf file.

> This section contains information on the following procedures:

> - Minimum Requirements
> - Compiling Apache With mod_proxy Module
> - Modifying the httpd.conf File
> - Starting And Stopping Apache

> ### Minimum Requirements

> You must meet the following requirements to successfully compile Apache web server and use the mod_proxy plug-in.

> - apache_1.3.27 (sources)
> - Sun’s C Compiler for Solaris 8 and 9.
> - Sun Java System Application Server, Standard Edition installables.
> - On Solaris 8 and 9, ensure that CC and make are in the PATH.

> ### Compiling Apache With mod_proxy Module

> 1. Download the latest Apache source distribution with built-in mod_proxy module from www.apache.org

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

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

> 3. 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:

> 1. 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.
> 2. 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.

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

> 5. 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 Application Server’s Reverse Proxy Plug-in. 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 Java System Application Server:

> <IfModule mod_proxy.c>
> ProxyPass /application http://<appserver.some.domain>:<port>/
> ProxyPassReverse /application http://<appserver.some.domain>:<port>/
> </IfModule>

> Here, <appserver.some.domain>:<port> should be replaced by the URL address of your Sun Java System Application Server. Duplicate these two lines for each web application context root, where /application is the web application context root and http://<appserver.some.domain>:<port> is the URL of the Sun Java System 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.

> Previous Contents Index Next

> Copyright 2004 Sun Microsystems, Inc. All rights reserved.