Previous      Contents      Index      Next
Sun Java System Application Server Enterprise Edition 7 2004Q2 Getting Started Guide

Chapter 3
Enterprise Features Configuration Tutorial

This chapter includes a tutorial to set up and use features in your Sun Java System Application Server environment. This chapter contains the following sections:

Preparing to Use the Tutorials
Overview of Tutorial Steps
Starting the Server
Verifying Server Start-up
Creating the loadbalancer.xml File
Adding a Cluster to the loadbalancer.xml File
Configuring Load Balancing
Sample loadbalancer.xml File

---

Preparing to Use the Tutorials

This guide walks you through setting up a clustered environment, deploying an application to it, and testing the load balancing and HTTP session persistence features with the application. It includes two tutorials: the Enterprise Features Configuration Tutorial, which covers configuring the cluster and load balancer, and the Cluster JSP Sample Application Tutorial, which covers deploying the application and verifying that load balancing and session persistence work.

This section contains the following topics:

Installation Requirements
Required Steps Before Using the Tutorials

Installation Requirements

The installation configuration suggested here is a basic, single-machine configuration for use with this guide. It is not necessarily the right configuration for your environment. You need to carefully consider your needs before deploying the Sun Java System Application Server in your environment. For more information on recommended configurations, see the Sun Java System Application Server System Deployment Guide.

For the purposes of doing the tutorials included in this book, use the following basic configuration:

One Sun Java System Web Server
One load balancer plug-in
One Sun Java System Application Server installation with two server instances configured to use high-availability databases
One high-availability databases

Note	All the instructions in this guide assume that you are using the Sun Java System Web Server. You can also use the Apache web server. For more information on using the Apache web server, see the Sun Java System Application Server Administration Guide.

Required Steps Before Using the Tutorials

Before you start the tutorials, you must have already completed the following steps.

Table 3-1  Steps for Preparing to Use the Tutorials

Step	Location of Instructions
1.  Install Sun Java System Web Server	Sun Java System Web Server Installation Guide
2.  Install Sun Java System Application Server, including: The load balancer plug-in The HADB	Sun Java System Application Server Installation Guide
3.  Set up the following for your machine: Shared memory Communication using rsh or ssh Environment variables for using the HADB	Sun Java System Application Server Installation Guide
4.  Run clsetup to perform the following configuration: Create and configure two application server instances, server1 and server2, in the domain domain1 Create the HADB. Create the database tables required to store session information in the HADB. Create a connection pool in the instances Create a JDBC resource in all the instances. Configure the session persistence information in the application server instances. Enable high availability in the application server instances.	Sun Java System Application Server Installation Guide

---

Overview of Tutorial Steps

The following table summarizes the steps required in the tutorials to configure your system, deploy an application, and verify the enterprise features. The left column describes the step, and the right column gives the location of the instructions needed to perform the step.

Table 3-2  Steps for Using Tutorials

Step	Location of Instructions
1.  Start the Admin Server and application server instances.	Starting the Server
2.  Verify that the Admin Server and application server instances are running.	“Verifying Server Start-up” on page 41
3.  Create a loadbalancer.xml file.	Creating the loadbalancer.xml File
4.  Set up a cluster in loadbalancer.xml.	Adding a Cluster to the loadbalancer.xml File
5.  Configure the load balancer in theloadbalancer.xml file.	Configuring Load Balancing
6.  Verify your loadbalancer.xml file against the sample loadbalancer.xml file.	Sample loadbalancer.xml File
7.  Deploy the sample application to the instances in your cluster using cladmin.	Deploying the Cluster JSP Sample Application to a Cluster
8.  Start the application server instances using cladmin.	Starting the Application Server Instances Using cladmin
9.  Verify that you deployed your application successfully.	Verifying Application Deployment
10.  Add the sample application to the cluster information in loadbalancer.xml.	Adding the Sample Application to the Cluster
11.  Apply changes and restart the web server.	Applying Configuration Changes and Restarting the Web Server
12.  Run the sample.	Running the Application
13.  Verify load balancing.	Verifying HTTP Load Balancing
14.  Verify session persistence.	Verifying HTTP Session Persistence
15.  Quiesce a server instance.	Quiescing a Server Instance

---

Starting the Server

Before you can use the tutorials in this guide, you need to start the Admin Server and all the application server instances in your cluster. Your Sun Java System Web Server should also be running.

The most straightforward way to start the Admin Server and the application server instances when all the server instances and the Admin Server are in a single domain is to use the asadmin utility’s start-domain command.

This section contains the following topics:

Setting the PATH Variable
Running asadmin start-domain

Setting the PATH Variable

Before running asadmin, for added convenience you can set your PATH variable.

Setting the PATH variable allows you to run asadmin, cladmin, and the asant (the application server’s Ant utility) from the command line at any location. Add the following directory to your PATH environment variable:

install_dir/bin

If you add the Application Server's bin directory to your login profile it is automatically added to your environment's PATH setting during login.

For example, add the following to your .cshrc file:

set path=( /opt/SUNWAppserver7/bin)

After you have saved the file, source it:

source .cshrc

You can test your change by executing the asadmin utility at the command prompt. Type:

asadmin

The following result should appear:

Use "exit" to exit and "help" for online help

asadmin>

Type exit to quit the asadmin interface.

If the command is not found:

Check that you have updated your PATH setting correctly.
If you updated your login file (for example, your .cshrc file), make sure you sourced the file. You might also need to start a new terminal window.

If you do not set the PATH environment variable, you can still run the commands and utilities from the directory where they are located (install_dir/bin), for example:

cd /opt/SUNWappserver7/bin

./asadmin

Running asadmin start-domain

To start the Admin Server and all the application server instances in it, run the asadmin start-domain command. At the command prompt, type:

asadmin start-domain --domain domain1

domain1 is the default domain configured when you installed the server and ran the clsetup command.

Note	In the configuration described in this guide, all the instances are in the same domain. If the server instances are not in the same domain, you need to run asadmin start-domain for every domain you plan to use. Once you have created a cluster, you can also use cladmin start-instance to start all the instances in a cluster. For information on cladmin syntax, see The cladmin Command Syntax.

Use the following command to stop both the Admin Server and the application server instances of the initially configured domain:

asadmin stop-domain --domain domain1

where domain1 is the name of the administrative domain defined during installation of the application server.

For a full list of asadmin commands, see the asadmin help. To access help, at the command prompt, type:

asadmin

Your prompt should change to the asadmin prompt, if you have set your PATH variable. Type help at the prompt to see a list of all asadmin commands. To get help on a specific asadmin command, at the asadmin prompt type the command name followed by the help option. For example:

asadmin> start-domain --help

---

Verifying Server Start-up

After starting the Admin Server and application server instances, verify that they have started successfully, as described in the following sections:

Verifying Admin Server Start-up
Verifying Start-up of Server Instances
Verifying Instances by Accessing the HTTP Server

Verifying Admin Server Start-up

You can verify that the Admin Server started by accessing the Sun Java System Application Server’s Administration interface, or by viewing the Admin Server’s event log, as described in the following sections:

Accessing the Administration Interface
Viewing the Admin Server’s Event Log

Accessing the Administration Interface

To verify that the Admin Server started correctly, you can access the Sun Java System Application Server’s web-based Administration interface. You can use this interface to administer the Sun Java System Application server instances, though for clustered instances it is more convenient and less error-prone to use the cladmin command.

Note	For a list of browsers compatible with the Administration interface, see the Sun Java System Application Server Platform Summary.

To access the Administration interface, follow these steps:

Open a browser window and specify the Admin Server port.

During installation, the default port number for the Admin Server is set to 4848. If this port was already in use or you selected another port number, then specify that port number.

For example:

http://test.sun.com:4848

Sign into the Administration interface using the administration user name and password supplied during product installation.

Tip	Forgot the user name or password? If you do not remember the Admin Server user name that was supplied during installation, try the user name admin, the default user name specified in the server configuration dialog during installation. If you don’t remember the administrator's password, look in the clpassword.conf file in the install_config_dir, created when you installed the server. You must be root to access this file.

Tip	Port not accessible? If the connection was refused when attempting to contact the Admin Server's Administration interface, it is likely that the Admin Server is not running. Check your start-up procedures and the content of the Admin Server's log file to determine the reason why the server is not running. For instructions on viewing the log file, see Viewing the Admin Server’s Event Log.

Once you've authenticated successfully, the initial screen of the Administration interface appears. When you click on an item in the left pane, the corresponding page appears in the right pane.

Viewing the Admin Server’s Event Log

You can also look in your Admin Server event log for a server start-up message. To open and view the event log file, follow these steps:

Navigate to the server logs for the Admin Server:

domain_config_dir/domain1/admin-server/logs/

Open server.log in an editor.

If your server has been started, you will find successful server startup at the end of the log file:

[20/Feb/2003:00:06:00] INFO ( 4318): CORE3274: successful server startup

If you don't see the successful start-up message, it could be because you have opened the event log file prior to the Admin Server completing its startup procedures. Close the log file and open it again to see the very latest event messages.

You can also use the tail -f command to view messages in the server log.

tail -f server.log

The -f option leaves the tail command running so new log entries are displayed as they are written to the file.

You can also access the Admin Server and the application server instance event log files through the Administration interface. Click the server name in the left pane (Admin Server or the application server instance) and click the Logging tab in the right pane.

For more information, see the Sun Java System Application Server Administration Guide.

Verifying Start-up of Server Instances

After running clsetup, you should have two server instances in domain1: server1 and server2. This section discusses two ways to verify that those instances exist, and to verify that they are running:

Verifying Instances using asadmin
Verifying Instances by Accessing the HTTP Server

Verifying Instances using asadmin

To verify, use the asadmin list-instances command:

Launch asadmin by typing asadmin at the command prompt:

asadmin

Your prompt becomes asadmin>

Use the list-instances command at the asadmin prompt to show all current instances.

list-instances

This command lists the instances and whether or not they are currently running. You should see two running instances, server1 and server2.

Verifying Instances by Accessing the HTTP Server

Another method to determine whether or not an application server instance has started is to access the instance's HTTP server welcome page through a web browser.

Using a browser, access the following location:

http://server_instance:server_instance_port_number

where server_instance_port_number is the HTTP server port number specified during installation or server instance creation.

Tip	If you do not remember the HTTP server port number of your server, you can inspect the application server instance's configuration file to determine the HTTP server port number: Navigate to the domain_config_dir/domain1/server_instance/config/ directory and open the server.xml file in your favorite editor. Look for the http-listener element, for example: http-listener id="http-listener-1" address="0.0.0.0" port="81"... In this case, port 81 is the HTTP port number in use.

If the application server instance is up and running normally, you should see the default HTTP server welcome page in your browser:

Tip	HTTP server welcome page: The HTTP server welcome page is an HTML page named index.html in the application server instance's default document directory. The application server instance's server.xml configuration file contains the setting for the default document root of the instance. After installation, the document root for the instance named server1 is set to domain_config_dir/domain1/server1/docroot/. You can find the welcome page at that location.

---

Creating the loadbalancer.xml File

After you have installed the components, run clsetup, and started the Admin Server, you are ready to configure your installation. The first step is to create a cluster.

Since the configuration of the cluster for this guide uses one load balancer plug-in, you must define the cluster in the web server’s loadbalancer.xml configuration file. This file belongs in the configuration file directory of your web server. The loadbalancer.xml file does not exist by default. You must create it.

To create the loadbalancer.xml file, follow these steps:

Find the sample loadbalancer.xml file, called loadbalancer.xml.example, located in your web server’s config directory.

By default, this directory is:

webserver_install_dir/servers/https-server_name/config

Save a copy of loadbalancer.xml.example as loadbalancer.xml.

You will edit this copy to include information for your environment, including information to create a cluster and allow load balancing to work.

An example loadbalancer.xml file is shown in Code Example 3-1.

Code Example 3-1  The loadbalancer.xml.example file

<!DOCTYPE loadbalancer PUBLIC "-//Sun Microsystems Inc.//DTD Sun ONE Application Server 7.0//EN" "sun-loadbalancer_1_1.dtd">

<loadbalancer>

  <cluster name="cluster1">

    <instance name="instance1" enabled="true" disable-timeout-in-minutes="60" listeners="<REPLACE_WITH_LISTENER1> <REPLACE_WITH_LISTENER2>"/>

    <web-module context-root="/abc" enabled="true" disable-timeout-in-minutes="60" enabled="true" />

    <health-checker url="/" interval-in-seconds="10" timeout-in-seconds="30" />

  </cluster>

  <property name="reload-poll-interval-in-seconds" value="60"/>

  <property name="response-timeout-in-seconds" value="30"/>

  <property name="https-routing" value="true"/>

  <property name="require-monitor-data" value="false"/>

</loadbalancer>

Notice the example file refers to the sun-loadbalancer_1_1.dtd, also found in the web server’s config directory.

---

Adding a Cluster to the loadbalancer.xml File

Next you need to add a cluster, for this tutorial called cluster1, to your loadbalancer.xml file. The cluster includes two Sun Java System Application Servers or server instances.

Edit your newly-created loadbalancer.xml to include the instances and the URLs to the HTTP listeners:

Go to your web server’s config directory and open loadbalancer.xml using a text editor.

Notice that the sample file already includes a cluster called cluster1.

<cluster name=“cluster1”>

Add the two application server instances that you created with clsetup, server1 and server2, to cluster1.

Create an instance subelement of the cluster for each of the instances. The instances need to be enabled (enabled=true). You also need to add the URLs of the HTTP listeners. In the case of the default server instance (server1) and the second server instance you have added (server2), there is one HTTP listener each. You could have more in a different environment.

The sample loadbalancer.xml file contains the following lines that you can edit:

<instance name="instance1" enabled="true" disable-timeout-in-minutes="60" listeners="<REPLACE_WITH_LISTENER1> <REPLACE_WITH_LISTENER2>"/>

Replace “instance1” with “server1” for this tutorial.
Replace <REPLACE_WITH_LISTENER1> with the listener URL for your server instance, for example:

http://test.sun.com:81.

The listener URL consists of the server name and port. If the listener has security enabled, the URL starts with HTTPS. If the listener is not secure, the URL starts with HTTP. To find information on the HTTP listener for each Sun Java System Application Server instance:

In the Administration interface, click the instance name to expand the tree view.
Click HTTP Server to expand it.
Under HTTP Server, click HTTP Listener.
The HTTP listener page gives you the port, the server name, and whether security is enabled.
Save your changes to loadbalancer.xml. Your file now has a line similar to the following:

<instance name="server1" enabled="true" disable-timeout-in-minutes="60" listeners="http://test.sun.com:81"/>

Change the disable-timeout-in-minutes value to 5.

The disable timeout in minutes is the instance-level quiescing period, in which you allow time for sessions to terminate for a server instance. The server is still running, but no requests that would result in new sessions are sent to it, though the server does accept requests that are for existing sessions. In the real world, this number would be quite high. The time specified in the example is 60 minutes. However, because the tutorial requires you to shut down the server, in this tutorial you are asked to set the timeout artificially low.

<instance name="server1" enabled="true" disable-timeout-in-minutes="5" listeners="http://test.sun.com:81"/>

Add a second instance to the cluster element. You can do that by copying the line above and pasting it below the existing line, then changing the server name and the listener URL. For example:

<instance name="server2" enabled="true" disable-timeout-in-minutes="5" listeners="http://test.sun.com:82"/>

Save your changes.

So far, your loadbalancer.xml file should look similar to the following:

<!DOCTYPE loadbalancer PUBLIC "-//Sun Microsystems Inc.//DTD Sun ONE Application Server 7.0//EN" "sun-loadbalancer_1_1.dtd">

<loadbalancer>

  <cluster name="cluster1">

    <instance name="server1" enabled="true" disable-timeout-in-minutes="5" listeners="http://test.sun.com:81"/>

    <instance name="server2" enabled="true" disable-timeout-in-minutes="5" listeners="http://test.sun.com:82"/>

    <web-module context-root="/abc" enabled="true" disable-timeout-in-minutes="60" enabled="true" />

    <health-checker url="/" interval-in-seconds="10" timeout-in-seconds="30" />

  </cluster>

  <property name="reload-poll-interval-in-seconds" value="60"/>

  <property name="response-timeout-in-seconds" value="30"/>

  <property name="https-routing" value="true"/>

  <property name="require-monitor-data" value="false"/>

</loadbalancer>

You’ll add information associated with the deployed application (the sample line that begins with “web-module”) during a later procedure.

Note	Enabling an application server instance in the loadbalancer.xml file is different from starting an application server instance. Even if the server is running and you have added it to the cluster, the load balancer does not route requests to the server instance until you enable it in loadbalancer.xml by setting the instance element’s enabled attribute to true.

---

Configuring Load Balancing

After creating the loadbalancer.xml file and adding a cluster, edit the loadbalancer.xml file to include the load balancer settings.

This section contains the following topics:

Configuring the Health Checker
Enabling Load Balancer Monitoring
Other Load Balancer Properties

Configuring the Health Checker

If you enable the health checker, the load balancer periodically checks all the Sun Java System Application Server instances that are flagged as unhealthy to see whether they have become healthy. If an application server instance that was marked as unhealthy has become healthy, the instance is added to the list of healthy instances, and requests are once more routed to it.

You configure the health checker in the health-checker element in loadbalancer.xml. You configure the listener URL that the health checker pings to see if the server is running, as well as how often the health checker pings the server and how long the health checker waits for a response before marking the server as unhealthy.

The sample loadbalancer.xml file includes the following line, which you do not need to edit in order to complete the tasks in this guide.

health-checker url="/" interval-in-seconds="10" timeout-in-seconds="30" />

The health-checker url specifies the URL to ping to determine whether the server instance is healthy (that is, whether it is responding). The example shows a URL of "/". For example, if your listener URL is http://www.example.com:80, then a health checker URL of "/" pings http://www.example.com:80/. For the purposes of this guide, leave the value "/".
The interval-in-seconds attribute specifies the interval between load balancer health checks. You do not need to change the value from the default 10.
The timeout-in-seconds attribute specifies the interval within which the load balancer must receive a response from the pinged server instance in order for the server instance to be considered healthy. You do not need to change the value from the default 30.

For example, using the default values, the health checker follows these steps:

The health checker pings the unhealthy listeners using the health checker URL.
For each listener, it waits 30 seconds (timeout-in-seconds) for a response.

If the server responds within 30 seconds, the listener is marked healthy. If the server does not respond, the health checker considers the server to still be unhealthy.

The health checker waits ten seconds (the interval-in-seconds) before starting another cycle of health checks.

If there are no unhealthy instances when the health checker starts, it skips the first two steps.

Enabling Load Balancer Monitoring

The load balancer plug-in uses the web server logging mechanism to write log messages. When monitoring is enabled, the following information is logged to the web server log file:

Start/stop information for every request
Failover request information when a request is failed over from an unhealthy to a healthy instance
List of unhealthy instances logged at the end of every health checker cycle

Caution	When logging is enabled on the load balancer plug-in, and if the web server logging level is set to DEBUG or to print verbose messages, the load balancer writes HTTP session IDs in the web server log files. Therefore, if the web server hosting the load balancer plug-in is in the DMZ, we recommend that you do not use the DEBUG or similar log level in production environments. If you must use the DEBUG logging level, then you should turn off load balancer logging by setting require-monitor-data property to false in loadbalancer.xml.

To monitor load balancing, you need to:

Enable monitoring in loadbalancer.xml
Configure the web server to use verbose logging.

To enable monitoring in loadbalancer.xml, follow these steps:

Open loadbalancer.xml using a text editor.
Find the following line (it was part of the example loadabalancer.xml file):

<property name="require-monitor-data" value="false"/>

Change “false” to “true” to enable monitoring.
Save your changes and exit the file.

In addition, to change the default web server log level, follow these steps:

Turn on the Sun Java System Web Server’s verbose logging:

Go to the web server’s config directory. If you installed your Sun Java System Web Server in the default location, the path will be:

/web_server_install_dir/https-server_name/config

Open the magnus.conf file for editing.
Add the following line:

LogVerbose on

Save the changes to the file.
Restart the web server to apply the changes.

Other Load Balancer Properties

The example loadbalancer.xml contains the following additional load balancer properties:

<property name="reload-poll-interval-in-seconds" value="60"/>

<property name="response-timeout-in-seconds" value="30"/>

<property name="https-routing" value="true"/>

For this tutorial, you do not need to change the default values. For more information on these properties, see the following sections:

Dynamic Reconfiguration using the Reload Poll Interval
Response Timeout
HTTPS Routing

Dynamic Reconfiguration using the Reload Poll Interval

After the initial configuration, the load balancer plug-in detects changes to its configuration and loads them automatically. It detects changes by looking at the time stamp on the loadbalancer.xml file. If the time stamp has changed, the load balancer automatically reconfigures itself. The reload poll interval specifies how often the load balancer checks the time stamp.

Note	If the changes to the loadbalancer.xml file are not in the correct format as specified in the sun-loadbalancer_1_0.dtd file, the reconfigure operation fails. The failure notice is logged to the web server’s error log files. The load balancer will continue to use the old configuration that’s already loaded in memory. If the load balancer encounters a hard disk read error while attempting to reconfigure itself, it uses the configuration that is currently in memory. If a disk read error is encountered, a warning message is logged to the web server’s error log file. The Sun Java System Web Server’s error log file can be found at: web_server_install_dir/web_server_instance/logs/.

Response Timeout

The response timeout designates how long the server waits for the instance to respond to a request. After the specified number of seconds, if the instance has not responded an error message is sent to the browser.

HTTPS Routing

When HTTPS routing is disabled, HTTPS listeners listed in the loadbalancer.xml file are ignored, and only HTTP listeners are used for load balancing. When HTTPS routing is enabled, HTTPS requests are failed over only to HTTPS ports.

---

Sample loadbalancer.xml File

The following sample loadbalancer.xml file includes one cluster of two instances. Check the syntax of your loadbalancer.xml file against this example.

Code Example 3-2  The loadbalancer.xml File

<!DOCTYPE loadbalancer PUBLIC "-//Sun Microsystems Inc.//DTD Sun ONE Application Server 7.0//EN" "sun-loadbalancer_1_1.dtd">

<loadbalancer>

  <cluster name="cluster1">

    <instance name="server1" enabled="true" disable-timeout-in-minutes="5"

listeners="http://test.sun.com:81"/>

    <instance name="server2" enabled="true" disable-timeout-in-minutes="5"

listeners="http://test.sun.com:82"/>

    <web-module context-root="/abc" enabled="true" disable-timeout-in-minutes="60" enabled="true" />

    <health-checker url="/" interval-in-seconds="10" timeout-in-seconds="30" />

  </cluster>

  <property name="reload-poll-interval-in-seconds" value="60"/>

  <property name="response-timeout-in-seconds" value="30"/>

  <property name="https-routing" value="true"/>

  <property name="require-monitor-data" value="true"/>

</loadbalancer>

Now that you have configured the enterprise features, you can deploy and run the sample application. Continue on to Chapter 4, "Cluster JSP Sample Application Tutorial."

Previous      Contents      Index      Next

---

Copyright 2004 Sun Microsystems, Inc. All rights reserved.