test

Sun GlassFish Enterprise Server 2.1 High Availability Administration Guide

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.

Requirements for Using Apache Web Server

For the Apache Web Server, your installation must meet the minimum requirements.

With Apache, the load balancer plug-in requires:

The software sources are available at http://www.sunfreeware.com

In addition, before compiling Apache:

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.

  1. Untar http-2.0.59.tar and go to the directory httpd-2.0.59.

  2. Download the patch from http://issues.apache.org/bugzilla/attachment.cgi?id=16495 and save it as a file, for example, 12355.diff.

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

ProcedureTo Install SSL-aware Apache

Before You Begin

You must have already downloaded and uncompressed the Apache software.

  1. Download and unpack the OpenSSL source.

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

    For more information about OpenSSL, see the http://www.openssl.org/.

  3. Download and unpack Apache.

    Apache is available from http://httpd.apache.org.

  4. Compile and build Apache. Configure the source tree:

    1. For Apache 2.0.x, use this command: cd http-2.0_x. For Apache 2.2.x, use this command: cd http-2.2_x

    2. Run the following command:

      ./configure --with-ssl= OpenSSL-install-path --prefix= Apache-install-path --enable-ssl --enable-so

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

  5. For Apache on Linux 2.1, before compiling:

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

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

      LIBS+= -licuuc -licui18n -lnspr4 -lpthread -lxerces-c 
-lsupport -lnsprwrap -lns-httpd40
LDFLAGS+= -L/application-server-install-dir/lib -L/opt/sun/private/lib

      Note that -L/opt/sun/private/lib is only required if you installed Application Server as part of a Java Enterprise System installation.

      For example:

      ## (End of automatically generated section)
## 
CFLAGS=$(OPTIM) $(CFLAGS1) $(EXTRA_CFLAGS)
LIBS=$(EXTRA_LIBS) $(LIBS1)
INCLUDES=$(INCLUDES1) $(INCLUDES0) $(EXTRA_INCLUDES)
LDFLAGS=$(LDFLAGS1) $(EXTRA_LDFLAGS)
"LIBS+= -licuuc -licui18n -lnspr4 -lpthread 
-lxerces-c -lsupport -lnsprwrap -lns-httpd40
LDFLAGS+= -L/application-server-install-dir /lib -L/opt/sun/private/lib

    3. Set environment variable LD_LIBRARY_PATH.

      With stand–alone installations, add as-install/lib

      With Java Enterprise System installations, set it to the Enterprise Server: as-install/lib:opt/sun/private/lib.

      If you are using Solaris 9, add /usr/local/lib to the LD_LIBRARY_PATH.

  6. Compile Apache as described in the installation instructions for the version you are using.

    For more information, see the http://httpd.apache.org/

    In general, the steps are:

    1. make

    2. make install

    Note –

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

Exporting the DAS Certificate

You must manually export the DAS certificate using the following command: 

appserver-install-dir/lib/upgrade/certutil -L -d appserver-instance-dir/config -n s1as -a -o sjsas.crt

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:

##BEGIN EE LB Plugin Parameters
LoadModule apachelbplugin_module modules/mod_loadbalancer.so
#AddModule mod_apache2lbplugin.cpp
<IfModule mod_apache2lbplugin.cpp> 
  config-file webserver-instance/httpd/conf/loadbalancer.xml
  locale en
</IfModule>
<VirtualHost machine-ip-address>
  DocumentRoot "webserver-instance/httpd/htdocs"
  ServerName server-name
</VirtualHost>
##END EE LB Plugin Parameters

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

##BEGIN EE LB Plugin Parameters
LoadFile /usr/lib/libCstd.so.1 (For Solaris SPARC only)
LoadModule apachelbplugin_module modules/mod_loadbalancer.so
#AddModule apachelbplugin_module
<IfModule apachelbplugin_module> 
  config-file Apache-install-location/conf/loadbalancer.xml
  locale en
</IfModule>
##END EE LB Plugin Parameters

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

##BEGIN EE LB Plugin Parameters
<VirtualHost machine-ip-address> 
  ServerName host-name
 DocumentRoot Apache-install-location/htdocs
</VirutalHost>
##END EE LB Plugin Parameters

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:

Importing the DAS Certificate

The Enterprise Server installation program performs the following tasks for you.

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:

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:

Modifying directory access permissions to enable auto apply

To ensure that the Auto Apply feature operates correctly, grant the Apache user read access, write access, and execute access to the apache-install-location/conf/ directory.

If the Apache user is in the same group as the owner of this directory, change the mode to 775. If the Apache user is in a different group than the owner of this directory, change the mode to 777.

ProcedureTo Create a Security Certificate for Apache

These steps are required to support HTTPS requests on Apache.

For detailed information on setting up a security certificate on Apache, see the instructions on http://httpd.apache.org/docs/2.2/ssl/ssl_faq.html and http://www.modssl.org/docs/2.8/ssl_faq.html. The following procedure is adapted from those web sites.

  1. Set up the following environment variable:

    OPENSSL_CONF=OpenSSL-installation-directory/apps/openssl.cnf.

  2. Create the server certificate and key by executing the following command:

    openssl req -new -x509 -keyout newreq.pem -out newreq.pem -days 365

    When asked for a common name, give the host name on which you plan to run Apache. For all other prompts, enter values that meet any specific requirements you have.

    This command creates newreq.pem.

  3. Open the newly-created newreq.pem from the location where the openssl command was run.

  4. Copy the lines beginning with BEGIN CERTIFICATE and ending with END CERTIFICATE and paste them in Apache-install-dir/conf/ssl.crt/server.crt. For example:


    -----BEGIN CERTIFICATE-----
....
...
-----END CERTIFICATE-----

  5. Copy the lines beginning with BEGIN RSA PRIVATE KEY and END RSA PRIVATE KEY and paste them in Apache-install-dir/conf/ssl.key/server.key. For example:


    -----BEGIN RSA PRIVATE KEY-----
...
...
...
-----END RSA PRIVATE KEY-----

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

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

To start Apache in SSL mode, use one of the following commands:

apachectl startssl or apachectl -k start -DSSL on Apache 2.0.x. Use apachectl start on Apache 2.2.x.

If needed, check the Apache web site for the latest information on starting the Apache server.

Verifying the Setup

  1. Install the load balancer plug-in. For detailed steps to install the plug-in, see Sun GlassFish Enterprise Server 2.1 Installation Guide. During the installation, provide the path to the DAS certificate.

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

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

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

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