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.
Configuring Apache before Installing the HTTP Load Balancer Plug-in
Modifications made by the Installer to Apache Web Server Configuration
For the Apache Web Server, your installation must meet the minimum requirements.
With Apache, the load balancer plug-in requires:
openssl-0.9.7e (source)
httpd-2.2.10 (source) for Apache 2.2.x and httpd-2.0.59 (source) for Apache 2.0.x
gcc-3.3-sol9-sparc-local packages (for Solaris 9 SPARC).
gcc-3.3-sol9-intel-local packages (for Solaris 9 x86)
The pre-installed gcc (for Solaris 10)
flex-2.5.4a-sol9-sparc-local packages (for Solaris 9 SPARC)
flex-2.5.4a-sol9-intel-local packages (for Solaris 9 x86)
The pre-installed flex (for Solaris 10)
The software sources are available at http://www.sunfreeware.com
In addition, before compiling Apache:
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.
To use a C compiler other than gcc, set the path of the C compiler and make utility in the PATH environment variable.
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.
Untar http-2.0.59.tar and go to the directory httpd-2.0.59.
Download the patch from http://issues.apache.org/bugzilla/attachment.cgi?id=16495 and save it as a file, for example, 12355.diff.
From the directory httpd-2.0.59/modules/ssl, run the following command:
patch < 12355.diff
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.
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.
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.
For more information about OpenSSL, see the http://www.openssl.org/.
Download and unpack Apache.
Apache is available from http://httpd.apache.org.
Compile and build Apache. Configure the source tree:
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
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.
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:
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
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.
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:
For Apache 2.2.x, uncomment the following line in the apache-install-location/conf/httpd.conf file: Include conf/extra/httpd-vhosts.conf
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.
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:
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:
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:
[warn] RSA server certificate CommonName (CN) hostname does NOT match server name! |
For more information on installing certificates for Apache, see To Create a Security Certificate for Apache .
In config, replace ServerName www.example.com:80 with www.example.com with the hostname of the local system where Apache is installed.
Without this change, you see warnings when you start Apache that the system could not determine the server's fully qualified domain name, and that there are overlapping VirtualHost entries.
In apache-install-location/conf/extra/httpd-vhosts.conf, ServerName www.example.com:80 is replaced with www.example.com with the hostname of the local system where Apache is installed.
Without this change, you see warnings when you start Apache that the system could not determine the server's fully qualified domain name, and that there are overlapping VirtualHost entries.
The Enterprise Server installation program performs the following tasks for you.
Imports the DAS certificate by copying sjsas.crt to the apache-install-dir/conf/ssl.crt directory.
Appends the following lines to apache-install-dir/conf/extra/httpd-ssl.conf in Apache 2.2.x or to apache-install-dir/conf/httpd.conf in Apache 2.0.x.
<Location /lbconfigupdate> SSLVerifyClient require SSLVerifyDepth 1 SSLRequireSSL SSLCACertificateFile apache-install-dir//conf/ssl.crt/sjsas.crt SSLRequire ( %{SSL_CIPHER} !~ m/^(EXP|NULL)-/ \ and %{SSL_CLIENT_S_DN_O} eq "Sun Microsystems" \ and %{SSL_CLIENT_S_DN_OU} eq "Sun GlassFish Enterprise Server" \ and %{SSL_CLIENT_M_SERIAL} eq "<serial_number>" ) </Location> <Location /getmonitordata> SSLVerifyClient require SSLVerifyDepth 1 SSLRequireSSL SSLCACertificateFile apache-install-dir/conf/ssl.crt/sjsas.crt SSLRequire ( %{SSL_CIPHER} !~ m/^(EXP|NULL)-/ \ and %{SSL_CLIENT_S_DN_O} eq "Sun Microsystems" \ and %{SSL_CLIENT_S_DN_OU} eq "Sun GlassFish Enterprise Server" \ and %{SSL_CLIENT_M_SERIAL} eq <serial_number> ) </Location>
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.
This section requires the changes you make after installing Apache Web Server.
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 |
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.
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.
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.
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:
apache-install-location/conf/loadbalancer.xml
apache-install-location/conf/sun-loadbalancer_1_2.dtd
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.
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.
Set up the following environment variable:
OPENSSL_CONF=OpenSSL-installation-directory/apps/openssl.cnf.
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.
Open the newly-created newreq.pem from the location where the openssl command was run.
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----- |
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----- |
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.
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:
If you are a Java Enterprise System user.
If you've used port numbers which are less than 1024.
If Apache runs as a different user from the user that starts it.
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.
Install the load balancer plug-in. For detailed steps to install the plug-in, see Sun GlassFish Enterprise Server v2.1.1 Installation Guide. During the installation, provide the path to the DAS certificate.
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.