Chapter 4 Configuring Web Servers
for HTTP Load Balancing

This chapter explains how to configure the web servers supported by
the HTTP load balancer plug-in. The HTTP load balancer plug-in supports the
following web servers:

Sun Web Server 6.1 and 7.0 (32–bit)

Apache Web Server 2.2 and 2.0.x (32–bit)

Microsoft IIS 5.0 and 6.0 (32–bit)

Note –

The HTTP load balancer plug-in does not support web servers running
in 64–bit mode.

The HTTP load balancer plug-in installation program, which is a part
of the Enterprise Server installation program, makes a few modifications to the
web server’s configuration files. These changes depend upon the web
server you are using. In addition, for some web servers you must make manual
configurations in order for the HTTP load balancer to work properly.

Configuring Sun Web Server

For Sun Web Server,
when you install the load balancer plug-in using the installation wizard,
the installation wizard automatically does all the necessary configuration.
No manual configuration is required. The load balancer plug-in bundled with Enterprise Server supports
the following versions of Sun Web Server:

The order in which NameTrans entries appear in obj.conf is very important. The installer puts the NameTrans entries
in the correct location, but if you are editing obj.conf for
other purposes you must ensure that the order remains correct. In particular,
the load balancer info must come before the document-root function.
For more information on the obj.conf file, see Sun Java
System Web Server 7.0 Administrator’s Configuration File Reference on
docs.sun.com.

Append the following lines to the file web-server-install-dir/config/obj.conf:

Configuring Sun Java System Web Server to Use Auto
Apply

Auto Apply is a feature provided by Enterprise Server 9.1 to send the load
balancer configuration automatically over the wire to the web server configuration
directory. The following procedures explain how to configure Sun Java System
Web Server (versions 6 and 7) to use this feature.

To Set Up the HTTP Load Balancer in SSL Mode for Sun Web Server 6.1

Note –

You need to perform the steps in this section only if you want
to use the Auto Apply feature of the load balancer plug-in. This feature helps
to send the load balancer configuration automatically over the wire to the
web server configuration directory.

Using a browser, access the Admin GUI of Web Server and login.

Select your server instance and click on Manage.

Click on the Security tab.

Initialize the trust database by giving the username and password.
This could be done using either the certutil command or
the GUI. The following options of the certutil command
could be used to initialize the trust database:

certutil -N -P "https-instance-name-hostname-" -d .

When prompted by certutil, enter the password to encrypt your
keys. Enter a password, which will be used to encrypt your keys. The password
should be at least eight characters long, and should contain at least one
non-alphabetic character.

When prompted to enter a new password, specify your password.

Create a sample local Certificate Authority (CA) using the following
command:

When prompted to enter 0-7 for the type of certificate, type 1
for SSL Server. When the prompt reappears, specify 9.

When queried “Is this a critical extension [y/n]?,”
specify “y.”

Edit the current HTTP Listener socket by clicking on Preferences->Edit
Listen Socket. Enable the security and choose the certificate created in the
previous step.

If you wish to not use the GUI,
change the entry to read as follows : Change the tag so that the value of
security is "true." The tag must be altered to contain additional body content
and a closing tag. Be sure to remove carriage returns when adding the tag.

You can check the presence of this certificate by using the following
command, which would list the s1as certificate along with other CA certificates
including the default server certificate. Ensure that you type the command
in a single line.

If obj.conf does not contain the following
lines, please append them at the end of the file. If you are using Enterprise Server with
HADB bundle, this step is automatically performed by the installation program.

You can verify the above set up from the DAS using the steps provided
in the section Verifying the Setup. Instead
of using the local CA, you can use any other CA and server certificate. In
that case you can skip steps 5 and 6 listed in the previous section, but need
to import the server certificate that you obtained from other CAs.

To Set up the HTTP Load Balancer in SSL Mode for Sun Web Server 7

(Optional) Create the NSS database using the following command.
This step is not needed if the NSS database exists. Make sure that you type
the command in a single line.

If you are using GlassFish v2.1 or Enterprise Server without HADB
bundle, export the DAS certificate, named with the alias “s1as”
using the Java SE 5.0 security tool called keytool. While doing so, select
the -rfc option to export the certificate in the printable encoding format,
as defined by the Internet RFC 1421 standard.

From the command
line, you can use the following commands to export the DAS certificate:

where, <webserver_home> refers to the web server installation directory
and <CONFIG_NAME> refers to the configuration name created for the default
web server instance.

You can check the presence of this certificate
by using the following command, which would list the s1as certificate along
with other CA certificates including the default server certificate. Make
sure that you type the entire command in a single line.

You can also use the Web Server Admin Console to view this. Select the
configuration to which the certificate has been imported to (default config,
in this case), and then select the Certificates tab. To look at all the certificates
available, select the Certificate Authorities sub tab.

Make the following configuration changes to Web Server 7.0.

Append the following lines to obj.conffile
located at <WS_INSTALL_ROOT>/admin-server/config-store/<DEFAULT_CONFIG_NAME>/config/:

Test this setup from the GlassFish DAS to see if it communicates
with the configured HTTP Load Balancer over SSL. For more information, see Verifying the Setup.

Using Apache Web Server

The load balancer plug-in
supports Apache Web Server 2.2.x and 2.0.x. To use Apache Web Server, you
must perform certain configuration steps before and after installing the load
balancer plug-in. The load balancer plug-in installation also makes additional
modifications to the Apache Web Server. After the plug-in is installed, you
must perform additional configuration steps. The load balancer plug-in supports
only 32–bit versions of Apache Web Server.

On the Linux platform, install Sun GlassFish Enterprise Server on
the same machine.

On the Solaris 9 operating system, use pkgadd to
install gcc and flex. Note that pkgadd requires root access.

On the Solaris 9 operating system, ensure that gcc version
3.3 and make are in the PATH, and flex is installed.

On the Solaris 10 operating system, before running make for
OpenSSL, run mkheaders, located in /usr/local/lib/gcc-lib/sparc-sun-solaris2.9/3.3/install-tools on Solaris SPARC or /usr/local/lib/gcc-lib/i386-pc-solaris2.9/3.3/install-tools on Solaris x86.

If you are using gcc on Red Hat Enterprise
Linux Advanced Server 2.1, the version must be later than gcc 3.0.

Note –

To use a C compiler other than gcc, set the
path of the C compiler and make utility in the PATH environment
variable.

Applying the Apache Web Server Patch to Apache 2.0.x

Before installing the load balancer plug-in for Apache 2.0.x, apply
the patch for the Apache Web Server issue 12355. More details about this issue
are available at http://issues.apache.org/bugzilla/show_bug.cgi?id=12355.
This patch is required for the Auto Apply feature to work with Apache 2.0.x.
To apply the patch, follow these steps.

From the directory httpd-2.0.59/modules/ssl,
run the following command:

patch < 12355.diff

Configuring Apache before Installing the HTTP Load
Balancer Plug-in

The Apache source must be compiled and built to run with SSL. This section
describes the minimum requirements and high-level steps needed to successfully
compile Apache Web Server to run the load balancer plug-in. These requirements
and steps only apply to the Solaris and Linux versions of the software. For
information on the Windows version of Apache, see the Apache web site.

Note –

The instructions included here are adapted from the instructions
at http://httpd.apache.org/docs. For detailed
instructions on installing SSL-aware Apache, please see that web site.

To Install SSL-aware Apache

Before You Begin

You must have already downloaded and uncompressed the Apache software.

Download and unpack the OpenSSL source.

Compile and build OpenSSL.

For full installation
instructions, see the file named INSTALL in the directory
where you uncompressed OpenSSL. That file has information on installing OpenSSL
in a user-specified location.

In the above commands, x is the Apache version
number, open-ssl-install-path is the absolute path
to directory where OpenSSL is installed, and Apache-install-path is
the directory in which to install Apache.

Note that you only need
to use the --enable-ssl --enable-so options if your Apache
2 server will be accepting HTTPS requests.

Apache 2 .0.x has multithreaded
behavior if compiled with the --with-mpm=worker option.

Note –

With Apache 2.2, use the --with-included-apr option
to build the bundled Apache Portable Runtime (APR).

For Apache on Linux 2.1, before compiling:

Open src/MakeFile and find the end of the automatically
generated section.

Add the following lines after the first four lines after the automatically
generated section:

Exporting the DAS Certificate

This certificate will be required at the time of installing the load
balancer plug-in. Ensure you perform this task before you install the load
balancer plug-in.

Modifications made by the Installer to Apache Web
Server Configuration

The Enterprise Server installation program
makes the following modifications to Apache configuration while installing
the load-balancing pug-in. If you choose to install the load-balancing plug-in
manually, you need to perform these steps manually. The installation program
extracts the necessary files to the modules directory in
the web server’s root directory:

Note –

Ensure that you export the DAS certificate before installing the
load-balancing plug-in.

For Apache 2.0.x, the installer adds the following entries to the web
server instance’s httpd.conf file:

Other changes made by the installer to ensure that Apache's config-file and ssl-config have correct values
for your environment. The ssl-config file is located
at Apache-install-location/conf/ssl.conf in
Apache 2.0.x, or at Apache-install-location/conf/extras/httpd-ssl.conf. The config file is at Apache-install-location/conf/httpd.conf for Apache 2.0.x and for
Apache 2.2.x. The summary of changes made are as follows:

In ssl-config, for VirtualHost default:port the
default hostname and port is replaced with the hostname of the local system
where Apache is installed and the server's port number. Without this change,
the load balancer will not work. On Solaris Apache may not start and on Linux,
HTTPS requests may not work.

In ssl-config, for ServerName
www.example.com:443, www.example.com is replaced
with the hostname of the local system where Apache is installed.

Without
this change, the following warning appears when you start Apache if a security
certificate is installed:

For Apache 2.2.x, ensure that the line, Include conf/extra/httpd-ssl.conf is uncommented in the apache-install-dir/conf/httpd.conf file.

The value for serial-number needs to be generated
from the DAS certificate file. Use the following command for generating the serial-number: keytool -printcert -file sjsas.crt.
Change all lowercase characters to upper case in the output of this command
and use it as the serial-number. This command will
also print the name of the application server you are using.

Configuring Apache After Installing the HTTP Load
Balancer Plug-In

This section requires the changes
you make after installing Apache Web Server.

Modifying httpd.conf parameters to enable sticky
round robin

For the sticky round robin feature to work, make the following changes
in the apache-install-location/conf/extra/httpd-mpm.conf file for Apache 2.2.x or in the apache-install-location/conf/httpd.conf file
for Apache 2.0.x.

Under the section prefork MPM, ensure that the values
of the parameters StartServers and maxclients are
set to 1. Otherwise, every new session request will spawn a new Apache process
and the load balancer plug-in will be initialized resulting in requests landing
in the same instance.

For Apache 2.2.x, uncomment the following line in the apache-install-location/conf/httpd.conf file:

Include conf/extra/httpd-mpm.conf

Configuring security files to work with the load
balancer

Apache Web Server must have the correct security files to work
with the load balancer plug-in. The load balancer depends on the NSS (Network
Security Service) library, which requires these security database files. You
need to get these security database files from Enterprise Server, so an installation
of Enterprise Server must be available in a location accessible by the Web Server.

To configure security files to work with the load balancer:

For Apache 2.0.x, append /usr/lib/mps to LD_LIBRARY_PATH in the Apache-install-dir/bin/apachectl script.

For Apache 2.2.x, append /usr/lib/mps to LD_LIBRARY_PATH in the Apache-install-dir/bin/envvars file.

Providing access permissions to Apache user

Ensure that the Apache user has the required access permissions to the apache-install-location/conf/ directory
and files in this directory. The Apache user is the UNIX user under which
the Apache server responds to requests. This user is defined in the file httpd.conf. If you installed Apache as a root user, read the note
about configuring the Apache user and group in apache-install-location/conf/httpd.conf.

Note –

Ensure that your configuration of users and groups meets the security
requirements for this directory. For example, to restrict access to this directory,
add the Apache user to the same user group as the owner of the directory.

Load balancer plug-in initialization

To ensure that the load balancer plug-in is initialized when Apache
is started, grant the Apache user read access and write access to the following
files:

Make sure that the variables SSLCertificateKeyFileand SSLCertificateFile in Apache-install-dir/conf/ssl.conf for Apache 2.0.x or in Apache-install-dir/conf/extra/httpd-ssl.conf for Apache 2.2.x have the correct values.

Ensure that the ServerName is not www.example.com. The ServerName
should be the actual host name where Apache will run, matching the Common
Name you entered when creating the server certificate and key.

Starting Apache on Solaris and Linux

In general, you should start Apache with the same user that installed
the Enterprise Server. You must start Apache as root under the following circumstances:

Log in to the Application Server Admin Console and create
a new cluster. For steps to create a new cluster, refer to the Admin Console
Online Help.

Create a new HTTP Load Balancer. While creating the load balancer,
specify the web server host as the device host, web server SSL Port as the
device port and select the cluster you created in the previous step as the
target. For detailed steps to create a new HTTP Load Balancer, refer to the
Admin Console Online Help.

To verify that the communication between the DAS and the web
server is working properly, in the Admin Console, navigate to the HTTP Load
Balancers node and click the HTTP Load Balancer. In the Load Balancer Device
Settings page that appears, press the Test Connection button.

If
you have not enabled the Automatically Apply Changes option while creating
a load balancer, then you must manually export the load balancer configuration
by going to the Export tab and clicking Apply Changes now.

If the test connection fails, be sure to check the Application
Server domain logs and the web server logs to troubleshoot the problem. Also
check if all the configuration steps have been performed correctly.

Using Microsoft IIS

To use Microsoft Internet
Information Services (IIS) with the load balancer plug-in, follow the steps
provided in these sections.

To Configure Microsoft IIS to use the HTTP Load Balancer
Plug-in

Open the Internet Services Manager.

Select the web site for which you want to enable the plug-in.

This web site is typically named the Default Web Site.

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

Add a new ISAPI filter, following these steps:

Open the ISAPI Filters tab.

Click Add.

In the Filter Name field, enter Enterprise Server

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

Click OK, and close the Properties notebook.

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.

Check the Execute Permission checkbox.

Leave all
other permission-related check boxes are left unchecked.

Click Finish.

Add the path of the sun-passthrough.dll file,
the Enterprise Server as-install/bin and the Enterprise Server as-install/lib to the system’s PATH environment variable.

For IIS 6.0 users, configure the Load Balancer Web Service Extension
to run in IIS 6 using the following steps:

In the IIS manager, expand the local computer, and click Web Service
Extensions.

In the Tasks pane, select Add a new Web Service Extension.

Enter the name of the Extension as Sun-Passthrough and
click Add.

Type the path to sun-passthrough.dll, C:\Inetpub\wwwroot\sun-passthrough.

Click OK.

Select Set extension status to Allowed.

For IIS 6.0 users, create the file C:\inetput\wwwroot\sun-passthrough\lb.log and give NTFS write and modify permissions to the group IIS_WPG on the file.

Because IIS 6.0 runs in Worker Process
Isolation Mode, it runs the IIS server with the security privileges of the
group IIS_WPG.

Type the following in a web browser to access
the web application context root: http://web-server-name/web-application, where web-server-name is
the host name or IP address of the web server and web-application is
the context root that you listed in the C:\Inetpub\wwwroot\sun-passthrough\sun-passthrough.properties file.

Tip –

The ISAPI filter status should be green. To check the filter status,
access the web site's Properties notebook and click the ISAPI Filters tab.
If the status is not green, try sending any HTTP request to the IIS HTTP port.
It is OK if the request fails. Recheck the ISAPI filter status.

Automatically configured sun-passthrough properties

The
installer automatically configures the following properties in sun-passthrough.properties. You can change the default values.