test

Sun Java System Application Server Enterprise Edition 8.2 High Availability Administration Guide

Chapter 4 Configuring Web Servers for Load Balancing

The load balancer plug-in installation program makes a few modifications to the web server’s configuration files. The changes made depend upon the web server. In addition, for some web servers you must make manual configurations in order for the load balancer to work properly.

Note –

The load balancer plug-in can be installed either along with Sun Java System Application Server Enterprise Edition, or separately, on a machine running the supported web server. For complete details on the installation procedure, see Chapter 1, Installing Application Server Software, in Sun Java System Application Server Enterprise Edition 8.2 Installation Guide (if using the standalone Application Server) or Sun Java Enterprise System 5 Installation Guide for UNIX (if using Java Enterprise System).

Using Sun Java System Web Server

For Sun Java System Web Server, when you install the load balancer plug-in, the installation program automatically does all necessary configuration. No manual configuration is required.

The installation program adds the following entries to the Sun Java System Web Server’s configuration files:

To the web server instance’s magnus.conf file, it adds:

##EE lb-pluginInit 
fn="load-modules"
shlib="web-server-install-dir/plugins/lbplugin/bin/libpassthrough.so" 
funcs="init-passthrough,service-passthrough,name-trans-passthrough" Thread="no"
Init fn="init-passthrough"
##end addition for EE lb-plugin

To the web server instance’s obj.conf file, it adds:

<Object name=default>
NameTrans fn="name-trans-passthrough" name="lbplugin" 
config-file="web-server-install-dir/web-server-instance/config/loadbalancer.xml"
<Object name="lbplugin">
  ObjectType fn="force-type" type="magnus-internal/lbplugin"
  PathCheck fn="deny-existence" path="*/WEB-INF/*"
  Service type="magnus-internal/lbplugin" 
  fn="service-passthrough"
  Error reason="Bad Gateway" 
  fn="send-error" 
  uri="$docroot/badgateway.html"
</object>

In the above code, lbplugin is a name that uniquely identifies the Object, and web-server-install-dir/web-server-instance/config/loadbalancer.xml is the location of the XML configuration file for the virtual server on which the load balancer is configured to run.

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.

After installing, configure the load balancer as described in Setting Up HTTP Load Balancing.

Using Apache Web Server

To use Apache Web Server, you must perform certain configuration steps before 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 –

On Apache 1.3, when more than one Apache child processes runs, each process has its own load balancing round robin sequence. For example, if there are two Apache child processes running, and the load balancer plug-in load balances on to two application server instances, the first request is sent to instance #1 and the second request is also sent to instance #1. The third request is sent to instance #2 and the fourth request is sent to instance #2 again. This pattern is repeated (instance1, instance1, instance2, instance2, and so forth). This behavior is different from what you might expect, that is, instance1, instance2, instance1, instance2, etc. In Sun Java System Application Server, the load balancer plug-in for Apache instantiates a load balancer instance for each Apache process, creating an independent load balancing sequence.

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, depending on the version of Apache.

Minimum Requirements for Apache 1.3

With Apache 1.3, the load balancer plug-in requires:

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

For more information on mod_ssl, including the correct version of mod_ssl to use with your version of Apache, see http://www.modssl.org.

In addition, before compiling Apache:

Note –

To use C compiler other than gcc, set the path of the C compiler and make utility in the PATH environment variable. For example, with the sh shell: export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:application-server-install-dir/lib

Minimum Requirements for Apache 2

With Apache 2, 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.

Configuring Apache before Installing the Load Balancer Plug-in

Before installing the load balancer plug-in for Apache, install the Apache Web Server. 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, available at http://openssl.org.

  2. Compile and build OpenSSL.

    This step is not required on the Linux 3.0 platform if OpenSSL 0.9.7.e is installed. It is required for Linux 4.0.

    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.

    Follow one of these procedures, depending on the version of Apache:

    • For Apache 1.3, configure Apache with mod_ssl with the following steps:

      1. Unpack the mod_ssl source.

      2. Type the following:

        cd mod_ssl-2.8.n–1.3.x

      3. Type the following:

        ./configure –with-apache=../apache_1.3.x --with-ssl=../openssl-0.9.8b --prefix=Apache-install-path --enable-module=ssl --enable-shared=ssl --enable-rule=SHARED_CORE --enable-module=so

      In the above commands, n is the correct version of mod_ssl to use with your version of Apache, x is the Apache version number, and Apache-install-path is the directory in which to install Apache.

      For more information on mod_ssl, including the correct version of mod_ssl to use with your version of Apache, see http://www.modssl.org.

    • For Apache 2, 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 2, make sure Apache's ssl.conf and httpd.conf files contains 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 2 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 www.example.com:443, replace www.example.com with the hostname of the local system where Apache 2 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 2, see To Create a Security Certificate for Apache 2.

    • In httpd.conf, for ServerName www.example.com:80, replace www.example.com with the hostname of the local system where Apache 2 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.


      
      		

      

      


      • 

    


    If you installed apache as a root user, please be sure to read the note
on configuring the User and Group in apache-install-location/conf/httpd.conf. Apache runs as the user  described in httpd.conf. For the load balancer plug-in to be initialized when Apache is
started, the loadbalancer.xml file and the sun-loadbalancer_1_1.dtd file (found in apache-install-location/conf) must have file permissions in accordance to this user.
    


    6. 


  6. 

    For Apache on Linux 2.1, before compiling:
    


      


    1. 

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


      2. 


    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. 


    3. 

      Set environment variable LD_LIBRARY_PATH.
      


      With stand–alone installations, set it to the Application Server: install-dir/lib 

      


      With Java Enterprise System Installations, set it
to the Application Server: install-dir/lib:opt/sun/private/lib.
      


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


      4. 


    

    7. 


  7. 

    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. 


    2. 

      
make certificate (Apache 1.3 only)
      


      3. 


    3. 

      
make install

      


      4. 


    

    The command make certificate asks for a secure password.
Remember this password as it is required for starting secure Apache.
    


    8. 



Modifications Made by the Load Balancer Plug-in Installer



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



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


<VirtualHost machine-name:443>
##Addition for EE lb-plugin
LoadFile /usr/lib/libCstd.so.1
LoadModule apachelbplugin_module libexec/mod_loadbalancer.so
#AddModule mod_apachelbplugin.cpp
<IfModule mod_apachelbplugin.cpp> 
  config-file webserver-instance/conf/loadbalancer.xml
  locale en
</IfModule><VirtualHost machine-ip-address>
  DocumentRoot "webserver-instance/htdocs"
  ServerName server-name
</VirtualHost>
##END EE LB Plugin ParametersVersion 7


Note that for Apache 2, the module is mod_apache2lbpblugin.cpp. 


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.



ProcedureTo Configure Apache Security Files to Work with the
Load Balancer


    


  1. 

    Create a directory called sec_db_files under Apache-install-dir.
    


    2. 


  2. 

    Copy the security database files from Application Server to the directory
you created.
    


    Copy domain-dir/config/*.db to Apache-install-dir/sec_db_files.
    


    3. 


  3. 

    Depending on the platform, perform additional configuration.
    



      


    • 

      On the Solaris platform, for Java Enterprise System installations:
      


      Add the path /usr/lib/mps/secv1 to LD_LIBRARY_PATH in the Apache-install-dir/bin/apachectl script. The path must be added before /usr/lib/mps.
      


      • 


    • 

      On the Linux platform, for Java Enterprise System installation:
      


      Add the path /opt/sun/private/lib to LD_LIBRARY_PATH in the Apache-install-dir/bin/apachectl script. The path must be added before /usr/lib.
      


      • 


    • 

      On Microsoft Windows:
      


        


      1. 

        Add a new path to the Path environment variable.
        


        Click
Start ⇒ Settings ⇒ Control Panel ⇒ System ⇒ Advanced ⇒
Environment Variables ⇒ System Variables.
        


        Add the Application Serverinstall-dir/bin to the Path environment variable.
        


        2. 


      2. 

        Set the environment variable NSPR_NATIVE_THREADS_ONLY to
1.
        


        In the Environment Variables window, under System Variables,
click New. Enter Variable name of NSPR_NATIVE_THREADS_ONLY and
Variable value of 1.
        


        3. 


      3. 

        Restart the machine.
        


        4. 


      

      • 

    


    4. 




ProcedureTo Create a Security Certificate for Apache 2


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. 

    Go to the appropriate OpenSSL directory:
    



      

    • 

      If using Solaris 10, use the preinstalled OpenSSL for certificate
creation. cd /usr/sfw/bin

      



      • 

    • 

      If using Solaris 9 or Linux, go to the directory where you
installed OpenSSL. You should already have run configure and make for OpenSSL as instructed in To Install SSL-aware Apache.
      


      Set up an environment variable OPENSSL_CONF=OpenSSL-installation-directory/apps/openssl.cnf.
      



      • 

    


    2. 


  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. 


  3. 

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


    4. 


  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. 


  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. 


  6. 

    Make sure that the variables SSLCertificateKeyFileand SSLCertificateFile in Apache-install-dir/conf/ssl.conf have the correct values.
    


    7. 


  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.
    


    8. 



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.


Using Microsoft IIS



To configure Microsoft Internet
Information Services (IIS) to use the load balancer plug-in, modify certain
properties in Windows Internet Services Manager. The Internet Services Manager
is located in the Administrative Tools folder in the Control Panel folder.


Make these modifications after installing the Sun Java System Application Server.



ProcedureTo Configure Microsoft IIS to use the Load Balancer
Plug-in


    


  1. 

    Open the Internet Services Manager.
    


    2. 


  2. 

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


    This web site is typically named the Default Web Site.
    


    3. 


  3. 

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


    4. 


  4. 

    Add a new ISAPI filter, following these steps:
    


      


    1. 

      Open the ISAPI Filters tab.
      


      2. 


    2. 

      Click Add.
      


      3. 


    3. 

      In the Filter Name field, enter Application Server

      


      4. 


    4. 

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


      5. 


    5. 

      Click OK, and close the Properties notebook.
      


      6. 


    

    5. 


  5. 

    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. 


    2. 

      In the Alias field, type sun-passthrough .
      


      3. 


    3. 

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


      4. 


    4. 

      Check the Execute Permission checkbox. 
      


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


      5. 


    5. 

      Click Finish.
      


      6. 


    

    6. 


  6. 

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


    7. 


  7. 

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


      


    1. 

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


      2. 


    2. 

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


      3. 


    3. 

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


      4. 


    4. 

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


      5. 


    5. 

      Click OK.
      


      6. 


    6. 

      Select Set extension status to Allowed.
      


      7. 


    

    8. 


  8. 

    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.
    


    9. 


  9. 

    For all IIS users, restart the machine.
    


    10. 


  10. 

    Verify that the web server, load balancer plug-in, and Application Server are
operating correctly.
    


    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.
    


    


    11. 



Automatically configured sun-passthrough properties



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








Property 




Definition 




Default Value 













lb-config-file





Path to the load balancer configuration file 





IIS-www-root\sun-passthrough\loadbalancer.xml












log-file





Path to the load balancer log file 





IIS-www-root\sun-passthrough\lb.log












log-level





Log level for the web server 




INFO