Sun Java System Application Server 9.1 High Availability Administration Guide

Using Apache Web Server

The load balancer plug-in bundled with Application Server 9.1 supports Apache Web Server 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.

Note –

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

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

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

Before installing the load balancer plug-in for Apache, apply the patch for the Apache Web Server issue 12355. More details about this issue are available at This patch is required for the Auto Apply feature to work. 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 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 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 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, available at

  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

  3. Download and unpack Apache.

    Apache is available from

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

    1. cd http-2.0_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.

  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)
      "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, set it to the Application Server: as-install/lib

      With Java Enterprise System installations, set it to the Application 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

    In general, the steps are:

    1. make

    2. make install

  7. Make sure Apache's ssl.conf and httpd.conf files contain the correct values for your environment.

    • In ssl.conf, for VirtualHost default:port replace the default hostname and port 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.conf, for ServerName, replace 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 httpd.conf, for ServerName, replace 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.

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

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

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

Exporting and Importing 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.

The Application Server 9.1 installation program performs the following tasks for you.

Modifications Made by the Load Balancer Plug-in Installer

The load balancer plug-in installation program extracts the necessary files to the modules directory in the web server’s root directory:

It adds the following entries to the web server instance’s httpd.conf file:

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

Configuring Apache After Installing the Load Balancer Plug-In

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 Application Server, so an installation of Application Server must be available in a location accessible by the Web Server.

To configure Apache security files to work with the load balancer, do the following:

Append /usr/lib/mps to LD_LIBRARY_PATH in the Apache-install-dir/bin/apachectl script.

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 and The following procedure is adapted from those web sites.

  1. Set up the following environment variable:


  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:

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

    -----END RSA PRIVATE KEY-----
  6. Make sure that the variables SSLCertificateKeyFileand SSLCertificateFile in Apache-install-dir/conf/ssl.conf have the correct values.

  7. Ensure that the ServerName is not 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.

Modifying httpd.conf parameters to enable sticky round robin

For the sticky round robin feature to work, in the httpd.conf file, 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.

Starting Apache on Solaris and Linux

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

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

apachetl startssl or apachetl -k start -DSSL

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 Java System Application Server 9.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 FQDN of the web server host as the device host name, 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.