|
| |
| Sun Java System Application Server Enterprise Edition 7 2004Q2 Getting Started Guide | |
Chapter 4
Cluster JSP Sample Application TutorialThis chapter demonstrates simple HTTP failover using the load balancer plug-in. It does not describe all the features supported by the HTTP load balancer plug-in. For information on the other features offered by the load balancer plug-in, see Sun Java System Application Server Administration Guide.
This chapter contains the following sections:
Preparing to use the Cluster JSP Sample Application TutorialBefore you use this tutorial, you must have already:
- Successfully completed all the tutorial steps in Chapter 3, "Enterprise Features Configuration Tutorial."
- Made a copy of the sample applications, if necessary.
You may need to make a copy of the samples if you are either sharing your application server installation with other users or your system user ID does not have write permissions to the area in which the application server is installed.
To copy the samples, copy the install_dir/samples directory to a location in which your user ID has write permissions.
For example:
cp -r install_dir/samples user_sample_directory
The samples directory contains the subdirectory ee-samples which contains the sample used in this guide.
If you are using a copy of the samples, as you proceed with this guide, replace install_dir/samples/ with the location of your own copy of the sample applications.
Deploying the Cluster JSP Sample Application to a ClusterThe Cluster JSP sample application demonstrates how a request to a JSP can be load balanced between application servers in a cluster. It has a shopping cart which demonstrates how HTTP session information persists, even if an application server has an outage.
The sample application comes with a WAR file that is ready to deploy as a web application. You do not need to compile or assemble the application.
To deploy the sample application to a cluster, you must first deploy it to every instance in the cluster.
Use the cladmin command to deploy an application to all instances in your cluster at once. The cladmin command runs an asadmin command on all instances in a cluster simultaneously. The cladmin command is located in install_dir/bin.
This section contains the following topics:
Input Files for the cladmin Command
The cladmin command uses two input files: clinstance.conf and clpassword.conf.
These files are located in the install_config_dir. Since you used these files to run clsetup earlier, these files should have the correct values for your environment.
Because many of the values you would have to specify to run cladmin deploy are included in these files, you can run the deploy command with a minimum of options.
The cladmin Command Syntax
The syntax of the cladmin command is as follows:
cladmin [--help] [--instancefile instance_file_location] [--passwordfile password_file_location] asadmin_command
where:
If the input files are located in the default location /etc/opt/SUNWappserver7, you can omit the instancefile and passwordfile options and run the command as follows:
cladmin asadmin_command
Running cladmin deploy
To deploy the application to all the instances in cluster, type:
cladmin deploy filepath
You can deploy the sample as a web application using the WAR file provided with the sample, the filepath is the path to the WAR file.
For example, if your Cluster JSP application is in the default location, type:
cladmin deploy /opt/SUNWappserver7/samples/ee-samples/clusterjsp/clusterjsp.war
If you have set your PATH variable, you can also go to the directory where the WAR file is located and deploy the application from there. For example:
cd install_dir/samples/ee-samples/clusterjsp
cladmin deploy clusterjsp.war
When you run the cladmin deploy command, you see messages as the application is deployed to each instance in the cluster.
If you encounter errors, consult the log file at /var/tmp/cladmin.log for more information.
The asadmin Commands Supported by the cladmin Command
You can use the cladmin command to run the following asadmin commands simultaneously for each application server instance in a cluster, except for configure-session-persistence:
For more information about the cladmin command, see the Sun Java System Application Server Administration Guide.
Requirements and Limitations
The cladmin command has the following requirements and limitations:
- All instances that are part of the cluster must have the same password for the administrator. The user name can be specified in the property name, user, in clinstance.conf file.
- Before running the command you must start the Admin Servers associated with all application server instances that are part of the cluster.
- The values specified in the input files will be same for all the instances in a cluster. The cladmin command is not designed to set up each instance with different values. For example, this command cannot create a JDBC Connection Pool with different settings for each instance.
Starting the Application Server Instances Using cladminAfter you deploy the sample application, verify that the server instances are running.
Verifying Application DeploymentOnce the application is deployed, you can run it in the Sun Java System Application Server instance to test the deployment. To run the sample application, follow these steps:
- From a browser, access the following URL:
http://host:application_server_instance_port/clusterjsp
For example:
http://test.sun.com:81/clusterjsp
- You see the page for this sample application.
Figure 4-1 Cluster JSP Sample Application Page
If you encounter an error, see Troubleshooting Deployment to an Application Server Instance.
- Enter some information in the session attribute fields and click ADD SESSION DATA.
The application displays your data.
- To verify deployment to the second instance, type the other instance’s port and hostname in the URL:
http://host:application_server_instance_port/clusterjsp
For example:
http://test.sun.com:82/clusterjsp
These URLs verify that the application was deployed to the application server instances. The application has not yet been added to the cluster in loadbalancer.xml, so you cannot yet verify it through the web server.
Monitoring the Sample in the Application Server
You can monitor the sample application by looking in the event log file of the application server instance. Each application server instance has its own event log.
This section contains the following topics:
Using the Administration Interface to View Logs
To use the Administration interface to view server instance log files:
If you would like to see more than 25 log entries, simply enter a larger number in the “Number of errors to view?” area and click OK to refresh the log display.
To use the Administration interface to view the HTTP access log for an application server instance:
The HTTP access log for a server instance shows the accesses to the sample application made for the server instance.
The name of the access log is access. By default, the access log file is located in the same directory as the server event log:
domain_config_dir/domain1/server1/logs/
Viewing Logs Using the tail Command
Using the tail -f command to monitor log files lets you see messages automatically as they are logged. In the Administration interface you must click a button to reflect new information on the page.
To use the tail -f command, follow these steps:
Application-Generated Messages in the Event Log
When your application writes information to stdout and/or stderr, by default, this information is recorded in the server instance’s event log as INFO-level messages with the message ID CORE3282 (stdout) and CORE3283 (stderr). While running the Cluster JSP sample, a number of application generated messages are written the server event log. The following excerpt provides a snapshot of some of these messages:
For example:
[13/Aug/2003:17:32:28] INFO ( 9657): CORE3282: stdout: No parameter entered for this request
[13/Aug/2003:17:32:34] INFO ( 9657): CORE3282: stdout: Add to session: name1 = 1
[13/Aug/2003:17:32:45] INFO ( 9657): CORE3282: stdout: Add to session: name2 = 2
[13/Aug/2003:17:32:52] INFO ( 9657): CORE3282: stdout: Add to session: name3 = 3
These messages show the changes in values as data is entered into the application’s user interface.
Application-Generated Messages in the Access Log
When you run the Cluster JSP sample, access log messages are logged to the application server instance that served the request:
192.18.151.14 - - [12/Aug/2003:15:34:52 -0700] "GET /clusterjsp/ HTTP/1.0" 302 1086
192.18.151.14 - - [12/Aug/2003:15:34:52 -0700] "GET /clusterjsp/HaJsp.jsp HTTP/1.0" 200 1578
Troubleshooting Deployment to an Application Server Instance
The most common problems when attempting to run this sample application are described in the following table. The left column shows the symptom, the middle column the probable cause of the problem, and the right column shows suggested solutions to try.
Table 4-2 Troubleshooting Deployment to Application Server Instance
Symptom
Probable cause
Solution
Connection failure when attempting to access first page.
Application server not started.
Wrong port specified in URL.
Ensure that the application server has been started.
Determine the correct HTTP server port number.
See Starting the Server for more details.
404 error when accessing main page.
Application not deployed.
See Deploying the Cluster JSP Sample Application to a Cluster.
When troubleshooting problems, it is very important that you monitor the application server log file. You may also find it useful to review the HTTP access log file to verify that HTTP requests are arriving at the application server as expected.
Adding the Sample Application to the ClusterOnce you have deployed the sample application to the two server instances in your cluster, you must add the application to the cluster you created in loadbalancer.xml:
- Go to your web server’s config directory and open loadbalancer.xml using a text editor.
- The sample loadbalancer.xml file contains the following line:
<web-module context-root="/abc" enabled="true" disable-timeout-in-minutes="60" enabled="true" />
Change this line to reflect the clusterjsp sample application:
<web-module context-root="clusterjsp" enabled="true" disable-timeout-in-minutes="60"/>
This line adds the clusterjsp application to the cluster and enables it.
The context root is the same value as is set for the application in the Sun Java System Application Server instance’s server.xml file.
The disable-timeout-in-minutes attribute is set to 60. If the application is disabled, there is a 60-minute application quiescing period for the server to finish servicing any outstanding requests for the application. Earlier we set the instance-level disable-timeout-in-minutes, which controls the quiescing period for a server instance.
- Save your changes.
Your loadbalancer.xml file should now be similar to the following file:
Code Example 4-1 The loadbalancer.xml File with Sample Application Configured
<!DOCTYPE loadbalancer PUBLIC "-//Sun Microsystems Inc.//DTD Sun Java System Application Server 7.0//EN" "sun-loadbalancer_1_0.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="clusterjsp" enabled="true" disable-timeout-in-minutes="60"/>
<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>
Applying Configuration Changes and Restarting the Web ServerAfter you have completed your loadbalancer.xml edits, you need to start your web server, or if your web server is already running, you need to apply your configuration changes and restart the web server.
To start your web server:
You may also need to start the web server’s administration server, located at web_server_install_dir/https-admin-serv.
To apply changes to a running web server and restart it:
- Access the Server Manager for the web server by typing the appropriate URL into your web browser.
http://web_server:web_server_admin_port
For example:
http://test.sun.com:8888
- Choose your server from the server manager and click Manage.
The Server Manager for the web server instance is displayed.
- A message warns that you have made manual changes to your configuration files and you have to apply changes.
- Click the Apply link in the upper right of the page.
- Click Apply Changes to apply the changes and restart the server.
For subsequent loadbalancer.xml changes, you do not need to apply changes and restart the server. All subsequent changes are loaded automatically because the reload poll interval is set. For more information, see Dynamic Reconfiguration using the Reload Poll Interval.
Running the ApplicationAfter you have deployed the application to all instances and updated the loadbalancer.xml file, test the application on the web server to make sure it works.
- From a browser, access the following URL:
http://host:web_server_port/clusterjsp
For example:
http://test.sun.com:80/clusterjsp
You see the page for this sample application.
Figure 4-2 Cluster JSP Sample Application Page
Your server information is listed at the top of the page, along with a unique Session ID. If you are accessing this application on the application server instance directly, the port information at the top of the page is the application server information. If you are accessing a clustered application through the web server, the port information is the web server information.
- Enter a name and value for the session attribute and click Add Session Data.
Your session data is displayed.
Figure 4-3 Session Data Displayed in Cluster JSP
Notice the Session ID at the top of the page. If you entered the session attributes and clicked ADD SESSION DATA before the session timed out, the Session ID at the top of the page will be the same as the first access.
In the example above, the Session ID d8bf64b4dd0146c7ff47b943cf52 is the same in both cases.
If the session timed out, the Session ID will be different.
- Enter a new session attribute name and value. If the session has not timed out, all attributes are listed in the Data Retrieved from HttpSession area.
For example, if you enter session attribute data twice more before the session timed out, a page similar to the following is displayed:
Figure 4-4 Cluster JSP Sample Application with Multiple HTTP Session Attributes
- If you wait until the session times out (1800 seconds) and enter new session attribute data, you see only the latest data you entered, and a new session ID at the top of the page.
You can also simulate a timeout by clicking CLEAR SESSION, which will clear your session data and give you a new session ID.
Figure 4-5 Cluster JSP with New HTTP Session Information
Notice a new Session ID (in this example, d8ca7921435686ffffffff996dc3bbf9c5489) appears at the top of the page and that only the latest information entered (in this example, test4=4) appears in the Data Retrieved from HttpSession section.
Verifying HTTP Load BalancingNow that you have run the sample application and are familiar with how the session information is presented, you can demonstrate that your load balancer is working. If not, you can troubleshoot your load balancer.
This section contains the following topics:
Steps for Verifying Load Balancing
You can demonstrate that the load balancer is working by following these steps.
- Open two separate browsers and run the application from your web server by typing http://web_server_name:web_server_port/clusterjsp. For example:
http://test.sun.com:80/clusterjsp
Because session data is sticky when you use the load balancer, if you open a browser window and access the application, all reloads or other operations from that browser are considered to be in the same session and will be serviced by a single Sun Java System Application Server instance.
In order to verify that load balancing is working for the application, open a second browser and access the application. Because the session data is stored in cookies, you must either open the second browser on a different machine, or use different browser software on the same machine. Check the Session ID to make sure both browser windows have separate session data.
- Once you have accessed the application in two separate session windows, open another browser window and look at the web server error log.
- Access your Sun Java System Web Server’s Administration Server with the URL described in your web server documentation, for example:
http://test.sun.com:8888
- Choose your web server instance and click Manage.
- In the Server Manager for your web server instance, click the Logs tab.
- In the left pane, click View Error Logs.
- Look for entries with RequestExit in them.
You can either scan for them visually or enter RequestExit into the “Only show entries with” field.
- The entries with RequestExit should show HTTP listener IDs for both Sun Java System Application Server instances, so you can see that both application server instances are serving requests.
- To verify that the Sun Java System Application Server instance serviced the request, check the HTTP access logs for each application server instance.
You should see the requests for the clusterjsp application. For more information on checking the access logs, see Using the Administration Interface to View Logs.
Note
In order to see the RequestExit messages, you must have enabled verbose logging for your web server. For instructions, see Enabling Load Balancer Monitoring.
If you are having trouble getting your load balancer to work, see the following section on troubleshooting your load-balancer plug-in.
Troubleshooting the Load-Balancer Plug-in
Use the following table to help you troubleshoot load balancing. The symptom is described in the left column, the probable cause in the middle column, and the solution in the right column.
Table 4-3 Troubleshooting Load Balancing
Symptom
Probable cause
Solution
Connection failure when attempting to access application
Web server is not started
Wrong port specified in URL.
Ensure that the web server has been started.
Determine the correct web server port number.
See your web server documentation for more details.
404 error when accessing application
Application is not deployed.
Error in your loadbalancer.xml file
See Deploying the Cluster JSP Sample Application to a Cluster.
Errors in your loadbalancer.xml file are noted in the web server’s error log. For more information, see Finding Errors in Your loadbalancer.xml File.
Error page when accessing application
One or more of the servers in the cluster is not responding.
Make sure that the server instances in your cluster are running.
Check your error log to see if the health checker has found an unhealthy instance. For more information, see Using the Health Checker.
Finding Errors in Your loadbalancer.xml File
If you cannot reach the sample application through the web server URL, you might have a problem with your load balancer. If you can reach the applications through the individual application servers, you can determine that the problem is not with the application server instances.
Because the load balancer plug-in logs messages to the web server log files, you should check the web server error log files for more information.
You can view the error logs for the Sun Java System Web Server through the Server Manager:
- Access your Sun Java System Web Server’s Administration Server with the URL described in your web server documentation, for example:
http://test.sun.com:8888
- Choose your web server instance and click Manage.
- In the Server Manager for your web server instance, click the Logs tab.
- In the left pane, click View Error Logs.
- The default view shows 25 messages; you can increase the number if necessary.
If you are experiencing problems with the load balancer, you see messages that include “Failed to initialize load balancing subsystem.”
If the problem is that the your loadbalancer.xml file has errors, you may see a parser error that points you to the line in your loadbalancer.xml file that contains the error. For example, you might see something like:
[17/Jun/2003:09:57:44] catastrophe ( 5643): LBConfigParser.cpp@434: reports: lb.configurator: CNFG1000: Parsing of file :/usr/iplanet/servers/https-test.sun.com/config/loadbalancer.xml
Failed at line : 7 and column : 3.The error message is : No character data is allowed by content model
This message points you to the line with the error in theloadbalancer.xml file.
Correct the problem in the loadbalancer.xml file, apply changes and restart the web server, and try again.
Using the Health Checker
If your load balancer is running correctly, and you have set your web server’s LogVerbose to on, you see the health checker working in the web server’s log files:
[09/Apr/2003:13:36:02] verbose ( 7576): HealthChecker.cpp@153: reports: lb.monitor: HLCK1006:UnhealthyInstances cluster1 1049920562631 NoUnhealthyInstances
For instructions about turning on verbose logging, see Enabling Load Balancer Monitoring.
Regardless of whether you are using verbose logging, if one of your instances becomes unhealthy, the load balancer will flag it as unhealthy when an access attempt fails. If it remains unhealthy, the health-checker flags it as unhealthy again.
For example:
[17/Jun/2003:10:37:27] warning ( 5700): reports: lb.runtime: RNTM2024: Daemon http://test.sun.com:81 is unhealthy.
[17/Jun/2003:10:37:27] warning ( 5700): reports: lb.healthchecker: HLCK3003: Listener: http://test.sun.com:81 is detected to be still unHealthy in cluster: cluster1
The health checker continues to monitor the unhealthy instance and flags it as healthy again once it is running.
Verifying HTTP Session PersistenceOnce you have verified that load balancing works, you can verify HTTP session persistence. In session persistence, if one Sun Java System Application Server instance fails for some reason, the second instance will pick up the session and process the request.
To demonstrate that HTTP session persistence is working:
- Open a browser window.
- Access the application from the web server. For example:
http://test.sun.com:80/clusterjsp
- View the web server error log to see which server serviced the request (again, look for RequestExit entries).
- Shut down the Sun Java System Application Server instance that is serving the page.
You can use the Administration interface to shut it down:
- Reload the Cluster JSP sample application page.
The session ID and session attribute data is retained.
- Check the web server error log. Notice that the other Application Server instance is now servicing the request.
Session information should be saved after a server goes offline. The only time you might lose session data during a failure is if the failure occurs while the application is transferring data. In that case, you may see slightly older session data.
Quiescing a Server InstanceIn the real world, you would not shut down a server without attempting to have it complete existing sessions. Instead, you would shut down the server in a phased manner, in a process called quiescing.
To quiesce an application server instance, follow these steps:
- Open a browser window and access the Cluster JSP application through the web server port. Keep this window open.
- Determine which application server instance is serving the request.
Open a second browser window and access the server1 application server instance HTTP access log in the Administration interface. Look in the log for an access of the Cluster JSP application timed when you sent the request. If you see the access in the server1 log, then the server1 application server instance is serving the request. If you do not see such an entry in the access log, check the access log for the server2 application server instance. Leave the access log window open.
- Once you have verified the application server instance that is serving the request, disable that server instance in the loadbalancer.xml file.
Change enabled="true" to enabled="false" for the correct server instance. For example:
<instance name="server1" enabled="false" disable-timeout-in-minutes="5" listeners="http://test.sun.com:81"/>
- Save your loadbalancer.xml changes.
- Wait for the reload poll interval to pass, so that your new configuration is loaded.
For this tutorial, the reload poll interval is set to 60 seconds, so you only need to wait a minute.
- Once the reload poll interval has passed and your new configuration is loaded, the load balancer plug-in no longer sends requests that do not have existing sessions to that server instance. However, requests with existing sessions are still forwarded to the server instance for the quiescing period.
To see this, in your open Cluster JSP window, enter name and attribute information and click ADD SESSION DATA
- Go to the browser window that displays the HTTP access log for the server that served the initial request. Click OK to refresh the information.
Notice that even though the server is disabled in loadbalancer.xml, it is serving this request.
- Wait five minutes for the quiescing period to end, then use your open Cluster JSP application window to enter additional name attribute information and click ADD SESSION DATA.
The quiescing period is controlled by the disable timeout in minutes for the server instance. Earlier in the tutorial we set this to five minutes.
- Because the quiescing period has passed, the request is sent to a different application server instance.
To see this result, refresh your server instance’s HTTP access log. You should see no new requests.
- Open a third browser window and view the HTTP access log for the other server instance. You should see the Cluster JSP request being serviced by the second server instance.
You can then shut down the application server instance safely.
You can also quiesce an application to take it offline safely. For more information on application server instance and application quiescing, see the Sun Java System Application Sever Administration Guide.
