Installing and Configuring Sun Cluster HA for Apache Tomcat

This chapter explains how to install and configure Sun Cluster HA for Apache Tomcat.

This chapter contains the following sections.

• Installing and Configuring Sun Cluster HA for Apache Tomcat

• Sun Cluster HA for Apache Tomcat

• Planning the Sun Cluster HA for Apache Tomcat Installation and Configuration

• Installing and Configuring Apache Tomcat

• Verifying the Installation and Configuration of Apache Tomcat

• Installing the Sun Cluster HA for Apache Tomcat Packages

• Registering and Configuring Sun Cluster HA for Apache Tomcat

• Configuring Sun Cluster HA for Apache Tomcat in Zones

• Verifying the Sun Cluster HA for Apache Tomcat Installation and Configuration

• Understanding the Sun Cluster Apache Tomcat HA Parameter File

• Understanding Sun Cluster HA for Apache Tomcat Fault Monitor

• Debugging Sun Cluster HA for Apache Tomcat

Installing and Configuring Sun Cluster HA for Apache Tomcat

Table 1 lists the tasks for installing and configuring Sun Cluster HA for Apache Tomcat. Perform these tasks in the order they are listed.

Sun Cluster HA for Apache Tomcat

Apache Tomcat acts as a servlet engine behind an Apache web server, or you can configure it as a standalone web server that includes the servlet engine.

Apache Tomcat is freely available under Apache Software License and can be downloaded from http://jakarta.apache.org.

The Sun Cluster HA for Apache Tomcat data service provides a mechanism for orderly startup and shutdown, fault monitoring, and automatic failover of the Apache Tomcat service.

The following table describes the relation between the application components and the related Sun Cluster data service.

Planning the Sun Cluster HA for Apache Tomcat Installation and Configuration

This section contains the information you need to plan your Sun Cluster HA for Apache Tomcat installation and configuration.

Apache Tomcat and Solaris Containers

Sun Cluster HA for Apache Tomcat is supported in Solaris Containers, Sun Cluster is offering two concepts for Solaris Containers.

• Zones are containers which are running after a reboot of the node. These containers, combined with resource groups having the nodename nodename:zonename as a valid “nodename” in the resource groups nodename list.

• Failover Zone containers are managed by the Solaris Container agent, and are represented by a resource of a resource group.

About Horizontal Scalability

Sun Cluster includes a concept of horizontal scalability for data services called scalable service. Ip based load-balancing algorithms are integrated in this concept. Because of this reason you can scale horizontally without using hardware loadbalancers. For a more detailed discussion of this scalable service see Sun Cluster Concepts Guide for Solaris OS.

Before using the Sun Cluster HA for Apache Tomcat in a scalable configuration, it is necessary to have a closer look at the infrastructure of the cluster and the clients.

If your clients access your application using proxies, determine whether the used proxy stays the same during a session context. This is true for an intranet.

If the proxy changes during a session context it means, from the load-balancing point of view, that the source ip address is changing. This will spoil every ip based load-balancing, wether it is hardware or software.

Especially when your client accesses the server over the Internet, it is not guaranteed, that the source ip address remains the same during a session context.

Sun Cluster HA for Apache Tomcat can be configured two ways to get horizontal scalability.

1. Using Sun Cluster HA for Apache Tomcat in a purely scalable configuration.

2. Using Sun Cluster HA for Apache Tomcat in a multiple masters configuration.

The difference between the two configuration is in the way of accessing the nodes.

• A client accesses the scalable configuration by its shared address. In this case, Sun Cluster does the load-balancing.

• A client accesses a multiple masters configuration using each node's physical address. Load-balancing must be done outside of the cluster.

For more information about scalable data services, see Sun Cluster Concepts Guide for Solaris OS.

Both configuration options are discussed in the sectionsSun Cluster HA for Apache Tomcat as a scalable configuration and Sun Cluster HA for Apache Tomcat as a multiple master configuration.

Sun Cluster HA for Apache Tomcat as a scalable configuration

You can use Sun Cluster HA for Apache Tomcat in a scalable configuration if it is guaranteed, that the source ip address remains the same during a session context. This guarantee is achieved in example in an intranet.

If the source ip address might change during a session context and a scalable configuration is required, Apache Tomcat needs to be configured with session replication. This can be done by the application using a global file system or a database.

You will get a performance penalty from this approach.

You will get better performance using Tomcats inbound memory session replication for a scalable configuration with changing source ip addresses.

• You can achieve the session replication for Apache Tomcat 4.x by following the instructions at http://www.theserverside.com/resources/article.jsp?l=Tomcat.

• For Apache Tomcat 5.x, inbound memory session replication as a built-in feature, is on the feature list.

• For Apache Tomcat 3.x the inbound memory session replication is not configurable.

Sun Cluster HA for Apache Tomcat as a multiple master configuration

You can use Sun Cluster HA for Apache Tomcat in a multiple master configuration in the other scenarios. External load-balancing is required. A typical configuration uses the scalable Apache web server as a load balancer and configures one physical host name of an Apache Tomcat instance behind each instance of the Apache web server. Another option is to use a hardware load balancer, which handles the session context.

The difference between scalable and multiple masters configuration is only in the way, the clients access the cluster nodes. In a scalable configuration, they access the shared address. Otherwise the clients access the physical zone or hostnames.

Configuration Restrictions

The configuration requirements in this section apply only to Apache Tomcat.

If your data service configuration does not conform to these requirements, the data service configuration might not be supported.

Restriction to deploy Sun Cluster HA for Apache Tomcat in a scalable configuration

Deploy a scalable Sun Cluster HA for Apache Tomcat configuration only if either session replication, or reliable source ip addresses are achieved. Otherwise the behavior of the application becomes unpredictable.

Restriction for the Load_balancing_policy

Setting the resource parameter Load_balancing_policy to LB_STICKY is strictly required, if Sun Cluster HA for Apache Tomcat is deployed in a scalable configuration with reliable source ip addresses when no session replication is configured. Otherwise, the behavior of the application becomes unpredictable. In every other scalable configuration the Sticky Load_balancing_policy helps to get the more cache hits out of your caches.

Restriction for Scalable Services and Solaris Containers

Sun Cluster HA for Apache Tomcat can be deployed in scalable configurations in Solaris Containers only if you use the zone features of Sun Cluster 3.2.

Restriction for the Apache Tomcat smf Service Name in a Failover Zone

The Apache Tomcat configuration in a failover zone uses the smf component of Sun Cluster HA for Solaris Containers. The registration of the Apache Tomcatdata service in a failover zone defines an smf service to control the Apache Tomcat database. The name of this smf service is generated in this naming scheme: svc:/application/sczone-agents:resource-name. No other smf service with exactly this name can exist.

The associated smf manifest is automatically created during the registration process in this location and naming scheme: /var/svc/manifest/application/sczone-agents/resource-name.xml. No other manifest can coexist with this name.

Configuration Requirements

These requirements apply to Sun Cluster HA for Apache Tomcat only. You must meet these requirements before you proceed with your Sun Cluster HA for Apache Tomcat installation and configuration.

Your data service configuration might not be supported if you do not adhere to these requirements.

Location of the Tomcat Home Directory for Scalable or Multiple Masters Configurations

If you intend to install Apache Tomcat in a scalable resource group, create the Tomcat Home directory and its dynamic data on local storage.

This required because Apache Tomcat uses the directory structure to store its configuration, logs, deployed applications and so on.

If your local storage is not big enough, you can use a Global File System on the shared storage.

In this scenario, the deployment of Tomcat applications needs to occur on every node where Apache Tomcat is hosted.

Load Balancing for Multiple Master Configurations

If you intend to install Apache Tomcat in a multiple master configuration, an external load balancer is required.

Location of the Tomcat Home Directory for Failover Configurations

If you intend to install Apache Tomcat in a failover resource group, create the Tomcat Home directory on the shared storage. The location for the Tomcat Home directory can reside on a Global File System (GFS) or it can reside on a Failover File System (FFS) with an HAStoragePlus resource. It is best practice to store it on a FFS.

This is required because Apache Tomcat uses the directory structure to store its configuration, logs, deployed applications, and so on. It is not recommended to store the binaries local and the dynamic parts of the data on the shared storage.

It is best practice to mount Global File Systems with the /global prefix and to mount Failover File Systems with the /local prefix.

Apache Tomcat Component Dependencies

You can configure the Sun Cluster HA for Apache Tomcat data service to protect one or more Apache Tomcat instances. Each instance needs to be covered by one Apache Tomcat resource. The dependencies between the Apache Tomcat resource and other needed resources are described in Table 3, in Table 4, or in Table 5.

Because of the special requirements of a scalable configuration, you need no dependencies to storage or addresses, as long as every Apache Tomcat and its parameter file pfile is stored on the root file system. Otherwise follow Table 4.

A multiple master configuration is running on more than one nodes like a scalable configuration, but without a shared address. Because of the special requirements of a multiple masters configuration, you need no dependencies to storage or addresses, as long as every Apache Tomcat and its parameter file pfile is stored on the root file system. Otherwise follow Table 5.

If more elaborate dependencies are required, see the r_properties(5) and rg_properties(5) man pages for further dependencies and affinities settings.

For more detailed information about Apache Tomcat, refer to the http://jakarta.apache.org web page.

Apache Tomcat Configuration and Registration Files

Apache Tomcat component has configuration and registration files in the directory /opt/SUNWsctomcat/util . These files let you register the Apache Tomcat component with Sun Cluster.

Within these files, the appropriate dependencies have been applied.

# cd /opt/SUNWsctomcat
# 
# ls -l util
total 4
-rwx--x---   1 root     other        709 Apr 29 11:57 sctomcat_config
-rwx--x---   1 root     other        561 Apr 29 11:58 sctomcat_register
# more util/*g
::::::::::::::
util/sctomcat_config
::::::::::::::
#
# Copyright 2006 Sun Microsystems, Inc.  All rights reserved.
# Use is subject to license terms.
#

#ident   "@(#)sctomcat_config.ksh 1.2     06/03/08 SMI"

# This file will be sourced in by sctomcat_register and the parameters
# listed below will be used.
#
# These parameters can be customized in (key=value) form
#
#        RS - name of the resource for the application
#        RG - name of the resource group containing RS
#      PORT - name of the port number
#        LH - name of the LogicalHostname SC resource
#  SCALABLE - true for a scalable resource or false for a failover resource
#   NETWORK - false or true, false for multiple master configurations without
#             shared address, in this case SCALABLE will be ignored
#
#     PFILE - absolute path to the parameter file for the Tomcat resource
#    HAS_RS - name of the HAStoragePlus SC resource
#             (it can be a , separated list for the dependencies)
#
# The following variables need to be set only if the agent runs in a
# local zone
#      ZONE - the zone name where the Apache Tomcat should run in
#             Optional
#    ZONEBT - The resource name which controls the zone.
#             Optional
#   PROJECT - A project in the zone, that will be used for this service
#             specify it if you have an su - in the start stop or probe,
#             or to define the smf credentials. If the variable is not set,
#             it will be translated as :default for the smf manifest
#             Optional

RS=
RG=
PORT=
LH=
NETWORK=false
SCALABLE=false
PFILE=
HAS_RS=

# local zone specific options

ZONE=
ZONE_BT=
PROJECT=

Installing and Configuring Apache Tomcat

This section contains the procedures you need to install and configure Apache Tomcat.

For more information about Apache Tomcat, refer to the http://jakarta.apache.org web page.

Determine how Apache Tomcat will be deployed in Sun Cluster –

• Determine how many Apache Tomcat instances will be deployed.

• Determine which Cluster File System will be used by each Apache Tomcat instance.

• Determine the type of the target zone where you will install Apache Tomcat. Valid zone types are, the global zone, the failover zone, or a zone.

To install and configure Apache Tomcat in a global zone configuration, complete the following tasks:

• How to Enable Apache Tomcat to run in a Global Zone Configuration

• How to Install and Configure Apache Tomcat in the Global Zone

To install and configure Apache Tomcat in a zone configuration, complete the following tasks:

• How to Enable Apache Tomcat to run in a Zone Configuration

• How to Install and Configure Apache Tomcat in a Zone

To install and configure Apache Tomcat in a failover zone configuration, complete the following tasks:

• How to Enable Apache Tomcat to run in Failover Zone Configuration

• How to Install and Configure Apache Tomcat in a Failover Zone

You will find installation examples for each zone type in:

• Appendix A, Deployment Example: Installing Apache Tomcat in the Global Zone

• Appendix B, Deployment Example: Installing Apache Tomcat in a Failover Zone

• Appendix C, Deployment Example: Installing Apache Tomcat in a Non-Global Zone

How to Enable Apache Tomcat to run in a Global Zone Configuration

1. Become superuser or assume a role that provides solaris.cluster.verb RBAC authorization on one of the nodes in the cluster that will host Apache Tomcat.

2. Register the SUNW.gds and SUNW.HAStoragePlus resource type.

   # clresourcetype register SUNW.gds SUNW.HAStoragePlus

3. Create a failover resource group.

   ---

   Note –

   Perform this step only if you create a failover data service.

   ---

   # clresourcegroup create Apache Tomcat-failover-resource-group

4. (Optional) Create a resource for the Apache Tomcat Disk Storage.

   ---

   Note –

   Perform this step only if you create a failover data service.

   ---

   # clresource create \ > -g Apache-Tomcat-failover-resource-group \ > -t SUNW.HAStoragePlus \ > -p FilesystemMountPoints=Apache Tomcat- instance-mount-points Apache-Tomcat-has-resource

5. (Optional) Create a resource for the Apache Tomcat Logical Hostname.

   ---

   Note –

   Perform this step for a failover data service.

   ---

   # clreslogicalhostname \ > -g Apache Tomcat-failover-resource-group \ > -h Apache Tomcat-logical-hostname \ > Apache Tomcat-lh-resource

6. Enable the failover resource group that now includes the Apache Tomcat Disk Storage and Logical Hostname resources.

   ---

   Note –

   Perform this step for a failover data service.

   ---

   # clresourcegroup online -M -n current-node Apache Tomcat-failover-resource-group

7. (Optional) Create the resource group for the multiple masters data service.

   ---

   Note –

   Perform this step only if you create a multiple masters data service.

   ---

   # clresourcegroup create \ > -p Maximum_primaries=2 \ > -p Desired_primaries=2 \ > Apache-Tomcat-Scalable-resource-group

   If you need more nodes, adjust Maximum_primaries and Desired_primaries to the appropriate value.

8. (Optional) Create a resource for the Apache Tomcat Disk Storage if it is not in the root file system.

   ---

   Note –

   Perform this step only if you create a multiple masters data service.

   ---

   # clresource create \ > -g Apache-Tomcat-failover-resource-group \ > -t SUNW.HAStoragePlus \ > -p FilesystemMountPoints=Apache Tomcat- instance-mount-points Apache-Tomcat-has-resource

9. Enable the failover resource group that now includes the Apache Tomcat Disk Storage and Logical Hostname resources.

   ---

   Note –

   Perform this step only if you create a multiple masters data service.

   ---

   # clresourcegroup online -M Apache Tomcat-failover-resource-group

10. Create a failover resource group for the SharedAddress resource.

    ---

    Note –

    Perform this step only if you create a scalable data service.

    ---

    # clresourcegroup create Apache-Tomcat-SharedAddress-resource-group

11. Create the SharedAddress resource.

    ---

    Note –

    Perform this step only if you create a scalable data service.

    ---

    # clressharedaddress create \ > -g Apache-Tomcat-SharedAddress-resource-group\ > -h Apache-Tomcat-SharedAddress-hostname \ > Apache-Tomcat-SharedAddress-resource

12. Online the SharedAddress resource group.

    ---

    Note –

    Perform this step only if you create a scalable data service.

    ---

    # clresourcegroup online -M Apache-Tomcat-SharedAddress-resource-group

13. Create the resource group for the scalable service.

    ---

    Note –

    Perform this step only if you create a scalable data service.

    ---

    # clresourcegroup create \ > -p Maximum_primaries=2 \ > -p Desired_primaries=2 \ > -p RG_dependencies=Apache-Tomcat-SharedAddress-resource-group \ > Apache-Tomcat-Scalable-resource-group

    If you need more nodes, adjust Maximum_primaries and Desired_primaries to the appropriate value.

14. Create a resource for the Apache Tomcat Disk Storage if it is not in the root file system.

    ---

    Note –

    Perform this step only if you create a scalable data service.

    ---

    # clresource create Apache-Tomcat-has-resource \ > -g Apache-Tomcat-scalable-group \ > -t SUNW.HAStoragePlus \ > -p FilesystemMountPoints=Apache Tomcat- instance-mount-points

15. Enable the failover resource group that now includes the Apache Tomcat Disk Storage and Logical Hostname resources.

    ---

    Note –

    Perform this step only if you create a scalable data service.

    ---

    # clresourcegroup online -M Apache Tomcat-resource-group

How to Install and Configure Apache Tomcat in the Global Zone

1. Determine how Apache Tomcat will be deployed in Sun Cluster

   • Determine whether you will use Apache Tomcat as a failover a multiple master, or a scalable data service.

     For conceptual information on scalable and failover data services, see Sun Cluster Concepts Guide for Solaris OS.

   • Determine which user name will run Apache Tomcat.

   • Determine how many Apache Tomcat versions and instances will be deployed.

   • If more than one instance of a version will be deployed, determine whether they share the binaries.

   • Determine which Cluster File System will be used by each Apache Tomcat instance.

2. Become superuser or assume a role that provides solaris.cluster.modify and solaris.cluster.admin RBAC authorizations.

3. Create user and group if required.

   ---

   Caution –

   In this scenario, the deployment of Tomcat group and user needs to occur on every node where Apache Tomcat is hosted.

   ---

   If Apache Tomcat is to run under a non root user, you have to create the appropriate user, and the appropriate group. For these tasks use the following commands.

   1. Create the group by running the following command:

      # groupadd —g 1000 tomcat

   2. Create the user by running the following command:

      # useradd —u 1000 —g 1000 —d /global/tomcat —s /bin/ksh tomcat

4. If you are not logged in as root, switch to the appropriate user name.

   # su — user-name

5. Install Apache Tomcat.

   If you deploy Apache Tomcat as a failover data service, install Apache Tomcat onto a shared file system within Sun Cluster.

   It is recommended that you install Apache Tomcat onto shared disks. For a discussion of the advantages and disadvantages of installing the software on a local versus a cluster file system, see Determining the Location of the Application Binaries in Sun Cluster Data Services Planning and Administration Guide for Solaris OS.

   If you will deploy Apache Tomcat as a failover data service install the Apache Tomcat binaries on the shared storage on one node. If Apache Tomcat will be deployed as a scalable or a multiple master data service, install the Apache Tomcat binaries on the local storage on every node, that will host the Apache Tomcat data service.

   ---

   Note –

   Refer to http://jakarta.apache.org/tomcat/index.html for instructions about installing Apache Tomcat.

   ---

   If you deploy Apache Tomcat as a scalable data service for a scalable or a multiple masters configuration, repeat the following step at every node that will host Apache Tomcat.

6. Create the environment script.

   Create an Korn shell or a C shell script (dependent on the login-shell of your Apache Tomcat user name) to set the environment variables for Apache Tomcat. You must set the environment variables in a shell script and not in the users profile.

   With this mechanism you can install and run multiple Apache Tomcat versions and instances under one user name.

   ---

   Caution –

   These shell scripts must be available on every node that can host the Apache Tomcat data service. For a failover configuration, store them on the shared storage of the node or in the target zone. For a scalable or a multiple masters configuration, store them on the local file system of every node or on the shared storage. These scripts must not be different on the various nodes.

   ---

Example 1 Korn shell script to set the environment variables for Apache Tomcat 3.x/3.3

# more env.ksh
#!/usr/bin/ksh
#
# Environment for Tomcat
#
JAVA_HOME=/usr/j2se
export JAVA_HOME
JAKARTA_HOME=/global/mnt1/jakarta-3.3
export JAKARTA_HOME
TOMCAT_HOME=$JAKARTA_HOME
export TOMCAT_HOME

Example 2 C shell script to set the environment variables for Apache Tomcat 3.3/3.3

# more env.csh
#!/usr/bin/csh
#
# Environment for Tomcat
#

setenv JAVA_HOME /usr/j2se
setenv JAKARTA_HOME /global/mnt1/jakarta-3.3
setenv TOMCAT_HOME $JAKARTA_HOME

Example 3 Korn shell script to set the environment variables for Apache Tomcat 4.1.x

# more env.ksh
#!/usr/bin/ksh
#
# Environment for Tomcat
#
JAVA_HOME=/usr/j2se
export JAVA_HOME
CATALINA_HOME=/global/mnt1/jakarta-tomcat-4.1.18
export CATALINA_HOME

Example 4 C shell script to set the environment variables for Apache Tomcat 4.1.x

# more env.csh
#!/usr/bin/csh
#
# Environment for Tomcat
#
setenv JAVA_HOME /usr/j2se
setenv CATALINA_HOME /global/mnt1/jakarta-tomcat-4.1.18

The environment variables are version and configuration dependent.

How to Enable Apache Tomcat to run in a Zone Configuration

1. Become superuser or assume a role that provides solaris.cluster.verb RBAC authorization on one of the nodes in the cluster that will host Apache Tomcat.

2. Create and boot your zone Apache Tomcat-zone on all the nodes to host your Apache Tomcat data base.

3. Register the SUNW.gds and SUNW.HAStoragePlus resource type.

   # clresourcetype register SUNW.gds SUNW.HAStoragePlus

4. Create a failover resource group.

   ---

   Note –

   Perform this step only if you create a failover data service.

   ---

   # clresourcegroup create -n node1:Apache Tomcat-zone,node2:Apache Tomcat-zone \ Apache Tomcat-failover-resource-group

5. (Optional) Create a resource for the Apache Tomcat Disk Storage.

   ---

   Note –

   Perform this step only if you create a failover data service.

   ---

   # clresource create \ > -g Apache-Tomcat-failover-resource-group \ > -t SUNW.HAStoragePlus \ > -p FilesystemMountPoints=Apache Tomcat- instance-mount-points Apache-Tomcat-has-resource

6. (Optional) Create a resource for the Apache Tomcat Logical Hostname.

   ---

   Note –

   Perform this step for a failover data service.

   ---

   # clreslogicalhostname \ > -g Apache Tomcat-failover-resource-group \ > -h Apache Tomcat-logical-hostname \ > Apache Tomcat-lh-resource

7. Enable the failover resource group that now includes the Apache Tomcat Disk Storage and Logical Hostname resources.

   ---

   Note –

   Perform this step for a failover data service.

   ---

   # clresourcegroup online -M -n current-node Apache Tomcat-failover-resource-group

8. (Optional) Create the resource group for the multiple masters data service.

   ---

   Note –

   Perform this step only if you create a multiple masters data service.

   ---

   # clresourcegroup create \ > -p Maximum_primaries=2 \ > -p Desired_primaries=2 \ > -n node1:Apache Tomcat-zone,node2:Apache Tomcat-zone\ > Apache-Tomcat-Scalable-resource-group

   If you need more nodes, adjust Maximum_primaries and Desired_primaries to the appropriate value.

9. (Optional) Create a resource for the Apache Tomcat Disk Storage if it is not in the root file system.

   ---

   Note –

   Perform this step only if you create a multiple masters data service.

   ---

   # clresource create \ > -g Apache-Tomcat-failover-resource-group \ > -t SUNW.HAStoragePlus \ > -p FilesystemMountPoints=Apache Tomcat- instance-mount-points Apache-Tomcat-has-resource

10. Enable the failover resource group that now includes the Apache Tomcat Disk Storage and Logical Hostname resources.

    ---

    Note –

    Perform this step only if you create a multiple masters data service.

    ---

    # clresourcegroup online -M Apache Tomcat-failover-resource-group

11. Create a failover resource group for the SharedAddress resource.

    ---

    Note –

    Perform this step only if you create a scalable data service.

    ---

    # clresourcegroup create -n node1:Apache Tomcat-zone,node2:Apache Tomcat-zone\ > Apache-Tomcat-SharedAddress-resource-group

12. Create the SharedAddress resource.

    ---

    Note –

    Perform this step only if you create a scalable data service.

    ---

    # clressharedaddress create \ > -g Apache-Tomcat-SharedAddress-resource-group\ > -h Apache-Tomcat-SharedAddress-hostname \ > Apache-Tomcat-SharedAddress-resource

13. Online the SharedAddress resource group.

    ---

    Note –

    Perform this step only if you create a scalable data service.

    ---

    # clresourcegroup online -M Apache-Tomcat-SharedAddress-resource-group

14. Create the resource group for the scalable service.

    ---

    Note –

    Perform this step only if you create a scalable data service.

    ---

    # clresourcegroup create \ > -p Maximum_primaries=2 \ > -p Desired_primaries=2 \ > -p RG_dependencies=Apache-Tomcat-SharedAddress-resource-group \ -n node1:Apache Tomcat-zone,node2:Apache Tomcat-zone\ Apache-Tomcat-Scalable-resource-group

    If you need more nodes, adjust Maximum_primaries and Desired_primaries to the appropriate value.

15. Create a resource for the Apache Tomcat Disk Storage if it is not in the root file system.

    ---

    Note –

    Perform this step only if you create a scalable data service.

    ---

    # clresource create Apache-Tomcat-has-resource \ > -g Apache-Tomcat-scalable-group \ > -t SUNW.HAStoragePlus \ > -p FilesystemMountPoints=Apache Tomcat- instance-mount-points

16. Enable the failover resource group that now includes the Apache Tomcat Disk Storage and Logical Hostname resources.

    ---

    Note –

    Perform this step only if you create a scalable data service.

    ---

    # clresourcegroup online -M Apache Tomcatscalable-resource-group

How to Install and Configure Apache Tomcat in a Zone

1. Determine how Apache Tomcat will be deployed in Sun Cluster

   • Determine whether you will use Apache Tomcat as a failover a multiple master, or a scalable data service.

     For conceptual information on scalable and failover data services, see Sun Cluster Concepts Guide for Solaris OS.

   • Determine which user name will run Apache Tomcat.

   • Determine how many Apache Tomcat versions and instances will be deployed.

   • If more than one instance of a version will be deployed, determine whether they share the binaries.

   • Determine which Cluster File System will be used by each Apache Tomcat instance.

2. Become superuser or assume a role that provides solaris.cluster.modify and solaris.cluster.admin RBAC authorizations.

3. Enter the target zone

   # zlogin tomcat-zone

4. Create user and group if required.

   ---

   Caution –

   In this scenario, the deployment of Tomcat applications needs to occur on every zone where Apache Tomcat is hosted.

   ---

   If Apache Tomcat is to run under a non root user, you have to create the appropriate user, and the appropriate group. For these tasks use the following commands.

   1. Create the group by running the following command:

      # groupadd —g 1000 tomcat

   2. Create the user by running the following command:

      # useradd —u 1000 —g 1000 —d /global/tomcat —s /bin/ksh tomcat

5. If you are not logged in as root, switch to the appropriate user name.

   # su — user-name

6. Install Apache Tomcat.

   If you deploy Apache Tomcat as a failover data service, install Apache Tomcat onto a shared file system within Sun Cluster.

   It is recommended that you install Apache Tomcat onto shared disks. For a discussion of the advantages and disadvantages of installing the software on a local versus a cluster file system, see Determining the Location of the Application Binaries in Sun Cluster Data Services Planning and Administration Guide for Solaris OS.

   If you will deploy Apache Tomcat as a failover data service install the Apache Tomcat binaries on the shared storage on one zone. If Apache Tomcat will be deployed as a scalable or a multiple master data service, install the Apache Tomcat binaries on the local storage in every target zone, that will host the Apache Tomcat data service.

   ---

   Note –

   Refer to http://jakarta.apache.org/tomcat/index.html for instructions about installing Apache Tomcat.

   ---

   If you deploy Apache Tomcat as a scalable data service for a scalable or a multiple masters configuration, repeat the following step at every target zone that will host Apache Tomcat.

7. Create the environment script.

   Create an Korn shell or a C shell script (dependent on the login-shell of your Apache Tomcat user name) to set the environment variables for Apache Tomcat. You must set the environment variables in a shell script and not in the users profile.

   With this mechanism you can install and run multiple Apache Tomcat versions and instances under one user name.

   ---

   Caution –

   These shell scripts must be available on every node that can host the Apache Tomcat data service. For a failover configuration, store them on the shared storage in the target zone. For a scalable or a multiple masters configuration, store them on the local file system or on the shared storage of every target zone. These scripts must not be different on the various zones.

   ---

Example 5 Korn shell script to set the environment variables for Apache Tomcat 3.x/3.3

# more env.ksh
#!/usr/bin/ksh
#
# Environment for Tomcat
#
JAVA_HOME=/usr/j2se
export JAVA_HOME
JAKARTA_HOME=/global/mnt1/jakarta-3.3
export JAKARTA_HOME
TOMCAT_HOME=$JAKARTA_HOME
export TOMCAT_HOME

Example 6 C shell script to set the environment variables for Apache Tomcat 3.3/3.3

# more env.csh
#!/usr/bin/csh
#
# Environment for Tomcat
#

setenv JAVA_HOME /usr/j2se
setenv JAKARTA_HOME /global/mnt1/jakarta-3.3
setenv TOMCAT_HOME $JAKARTA_HOME

Example 7 Korn shell script to set the environment variables for Apache Tomcat 4.1.x

# more env.ksh
#!/usr/bin/ksh
#
# Environment for Tomcat
#
JAVA_HOME=/usr/j2se
export JAVA_HOME
CATALINA_HOME=/global/mnt1/jakarta-tomcat-4.1.18
export CATALINA_HOME

Example 8 C shell script to set the environment variables for Apache Tomcat 4.1.x

# more env.csh
#!/usr/bin/csh
#
# Environment for Tomcat
#
setenv JAVA_HOME /usr/j2se
setenv CATALINA_HOME /global/mnt1/jakarta-tomcat-4.1.18

The environment variables are version and configuration dependent.

How to Enable Apache Tomcat to run in Failover Zone Configuration

1. Become superuser or assume a role that provides solaris.cluster.verb RBAC authorization on one of the nodes in the cluster that will host Apache Tomcat.

2. As superuser register the SUNW.HAStoragePlus and the SUNW.gds resource types.

   # clresourcetype register SUNW.HAStoragePlus SUNW.gds

3. Create a failover resource group.

   # clresourcegroup create Apache Tomcat-resource-group

4. Create a resource for the Apache Tomcat zone`s disk storage.

   # clresource create -t SUNW.HAStoragePlus \ -p FileSystemMountPoints=Apache Tomcat-instance-mount-points \ Apache Tomcat-has-resource

5. (Optional) If you want the protection against a total adapter failure for your public network, create a resource for the Apache Tomcat`s logical hostname.

   # clreslogicalhostname create -g Apache Tomcat-resource-group \ -h logical-hostname \ Apache Tomcat-logical-hostname-resource-name

6. Place the resource group in the managed state.

   # clresourcegroup online -M Apache Tomcat-resource-group

7. Install the zone.

   Install the zone according to the Sun Cluster HA for Solaris Containers agent documentation, assuming that the resource name is Apache Tomcat-zone-rs and that the zone name is Apache Tomcat-zone.

8. Verify the zone's installation.

   # zoneadm -z Apache Tomcat-zone boot # zoneadm -z Apache Tomcat-zone halt

9. Register the zone's boot component.

   1. Copy the container resource boot component configuration file.

      # cp /opt/SUNWsczone/sczbt/util/sczbt_config zones-target-configuration-file

   2. Use a plain text editor to set the following variables:

      RS=Apache Tomcat-zone-rs
      RG=Apache Tomcat-resource-group
      PARAMETERDIR=Apache Tomcat-zone-parameter-directory
      SC_NETWORK=true|false
      SC_LH=Apache Tomcat-logical-hostname-resource-name
      FAILOVER=true|false
      HAS_RS=Apache Tomcat-has-resource
      Zonename=Apache Tomcat-zone
      Zonebootopt=zone-boot-options
      Milestone=zone-boot-milestone
      Mounts=

   3. Create the parameter directory for your zone's resource.

      # mkdir Apache Tomcat-zone-parameter-directory

   4. Execute the Sun Cluster HA for Solaris Container's registration script.

      # /opt/SUNWsczone/sczbt/util/sczbt_register -f zones-target-configuration-file

   5. Enable the Solaris Container resource

      # clresource enable Apache Tomcat-zone-rs

10. Enable the resource group.

    # clresourcegroup online Apache Tomcat-resource-group

How to Install and Configure Apache Tomcat in a Failover Zone

1. Determine how Apache Tomcat will be deployed in Sun Cluster

   • Determine whether you will use Apache Tomcat as a failover a multiple master, or a scalable data service.

     For conceptual information on scalable and failover data services, see Sun Cluster Concepts Guide for Solaris OS.

   • Determine which user name will run Apache Tomcat.

   • Determine how many Apache Tomcat versions and instances will be deployed.

   • If more than one instance of a version will be deployed, determine whether they share the binaries.

   • Determine which Cluster File System will be used by each Apache Tomcat instance.

2. Become superuser or assume a role that provides solaris.cluster.modify and solaris.cluster.admin RBAC authorizations.

3. (Optional) If you deploy Apache Tomcat in a non global zone, enter the target zone

   # zlogin tomcat-zone

4. Create user and group if required.

   If Apache Tomcat is to run under a non root user, you have to create the appropriate user, and the appropriate group. For these tasks use the following commands.

   1. Create the group by running the following command:

      # groupadd —g 1000 tomcat

   2. Create the user by running the following command:

      # useradd —u 1000 —g 1000 —d /global/tomcat —s /bin/ksh tomcat

5. If you are not logged in as root, switch to the appropriate user name.

   # su — user-name

6. Install Apache Tomcat.

   If you deploy Apache Tomcat as a failover data service, install Apache Tomcat onto a shared file system or in a failover zone within Sun Cluster.

   It is recommended that you install Apache Tomcat onto shared disks. For a discussion of the advantages and disadvantages of installing the software on a local versus a cluster file system, see Determining the Location of the Application Binaries in Sun Cluster Data Services Planning and Administration Guide for Solaris OS.

   If you will deploy Apache Tomcat as a failover data service install the Apache Tomcat binaries on the shared storage on one node or in the failover zone. If Apache Tomcat will be deployed as a multiple master data service, install the Apache Tomcat binaries on the local storage in every target zone, that will host the Apache Tomcat data service.

   ---

   Note –

   Refer to http://jakarta.apache.org/tomcat/index.html for instructions about installing Apache Tomcat.

   ---

   If you deploy Apache Tomcat as a multiple masters data service, repeat the following step at every node or target zone that will host Apache Tomcat.

7. Create the environment script.

   Create an Korn shell or a C shell script (dependent on the login-shell of your Apache Tomcat user name) to set the environment variables for Apache Tomcat. You must set the environment variables in a shell script and not in the users profile.

   With this mechanism you can install and run multiple Apache Tomcat versions and instances under one user name.

   ---

   Caution –

   These shell scripts must be available on every zone that can host the Apache Tomcat data service. For a failover configuration, store them on the shared storage of the node or in the target zone. For a multiple masters configuration, store them on the local file system or on the shared storage of the target zone. These scripts must not be different on the various zones. For an installation in afailover zone any place where the tomcat user has access is appropriate.

   ---

Example 9 Korn shell script to set the environment variables for Apache Tomcat 3.x/3.3

# more env.ksh
#!/usr/bin/ksh
#
# Environment for Tomcat
#
JAVA_HOME=/usr/j2se
export JAVA_HOME
JAKARTA_HOME=/global/mnt1/jakarta-3.3
export JAKARTA_HOME
TOMCAT_HOME=$JAKARTA_HOME
export TOMCAT_HOME

Example 10 C shell script to set the environment variables for Apache Tomcat 3.3/3.3

# more env.csh
#!/usr/bin/csh
#
# Environment for Tomcat
#

setenv JAVA_HOME /usr/j2se
setenv JAKARTA_HOME /global/mnt1/jakarta-3.3
setenv TOMCAT_HOME $JAKARTA_HOME

Example 11 Korn shell script to set the environment variables for Apache Tomcat 4.1.x

# more env.ksh
#!/usr/bin/ksh
#
# Environment for Tomcat
#
JAVA_HOME=/usr/j2se
export JAVA_HOME
CATALINA_HOME=/global/mnt1/jakarta-tomcat-4.1.18
export CATALINA_HOME

Example 12 C shell script to set the environment variables for Apache Tomcat 4.1.x

# more env.csh
#!/usr/bin/csh
#
# Environment for Tomcat
#
setenv JAVA_HOME /usr/j2se
setenv CATALINA_HOME /global/mnt1/jakarta-tomcat-4.1.18

The environment variables are version and configuration dependent.

Verifying the Installation and Configuration of Apache Tomcat

This section contains the procedure you need to verify the installation and configuration of Apache Tomcat.

How to Verify the Installation and Configuration of Apache Tomcat

This procedure does not verify that your application is highly available because you have not installed your data service yet.

1. Start the Apache Tomcat.

   Switch to the Tomcat user name in the target zone (in the following example, it is root) and change to the directory where the environment script is located. In the following example the Tomcat version is 4.1.24.

   ---

   Note –

   The output messages of the start and shutdown commands are highly version dependent.

   ---

   # . ./env.ksh # cd $CATALINA_HOME/bin # ./startup.sh Using CATALINA_BASE: /tomcat/jakarta-tomcat-4.1.24 Using CATALINA_HOME: /tomcat/jakarta-tomcat-4.1.24 Using CATALINA_TMPDIR: /tomcat/jakarta-tomcat-4.1.24/temp Using JAVA_HOME: /usr/j2se

2. Check the Installation

   Start a web browser and connect to the cluster node with http://nodename:8080. If you see the default Tomcat homepage everything is working correctly.

3. Stop the Apache Tomcat.

   # ./shutdown.sh Using CATALINA_BASE: /tomcat/jakarta-tomcat-4.1.24 Using CATALINA_HOME: /tomcat/jakarta-tomcat-4.1.24 Using CATALINA_TMPDIR: /tomcat/jakarta-tomcat-4.1.24/temp Using JAVA_HOME: /usr/j2se

How to Deploy the Apache Tomcat Application

If you configure Apache Tomcat as a failover resource, execute the following steps on one node. If you deploy Apache Tomcat as a scalable configuration, repeat the following steps on every node. If you deploy Apache Tomcat in a non global zone, regardless if it is a failover zone or a zone perform all the steps below in the target zone.

It is vital for a scalable configuration that the Apache Tomcat configuration does not differ on the Tomcat hosts.

1. Become superuser or assume a role that provides solaris.cluster.modify and solaris.cluster.admin RBAC authorizations.

2. (Optional) Enter the non global target zone.

   # zlogin zone-name

3. Modify the configuration files server.xml and the Tomcat user configuration to the desired content.

   For further information refer to http://jakarta.apache.org/tomcat/index.html.

4. Start Apache Tomcat as described in How to Verify the Installation and Configuration of Apache Tomcat.

5. Deploy your Application.

   For further information refer to http://jakarta.apache.org/tomcat/index.html.

6. Test your application with appropriate methods.

   For example, connect with a web browser to the Host with the appropriate port and select the start page of your application.

7. Stop Apache Tomcat as described in How to Verify the Installation and Configuration of Apache Tomcat.

   The port on which Apache Tomcat is serving is required for the configuration of the Sun Cluster Apache Tomcat resource.

   It is best practice to use the start page of the deployed application for the Fault Monitoring. In this case the TestCmd is described in Understanding the Sun Cluster Apache Tomcat HA Parameter File can be get /start_page. With this procedure, you monitor Apache Tomcat and the application it is serving.

8. (Optional) Leave the non global zone.

Installing the Sun Cluster HA for Apache Tomcat Packages

If you did not install the Sun Cluster HA for Apache Tomcat packages during your initial Sun Cluster installation, perform this procedure to install the packages. To install the packages, use the CommonInstaller.

How to Install the Sun Cluster HA for Apache Tomcat Packages

Perform this procedure on each cluster node where you are installing the Sun Cluster HA for Apache Tomcat packages.

You can run the CommonInstaller with a command-line interface (CLI) or with a graphical user interface (GUI). The content and sequence of instructions in the CLI and the GUI are similar.

Even if you plan to configure this data service to run in non-global zones, install the packages for this data service in the global zone. The packages are propagated to any existing non-global zones and to any non-global zones that are created after you install the packages.

Before You Begin

Ensure that you have the Sun Java^TM Availability Suite DVD-ROM.

If you intend to run the CommonInstaller with a GUI, ensure that your DISPLAY environment variable is set.

1. On the cluster node where you are installing the data service packages, become superuser.

2. Load the Sun Java Availability Suite DVD-ROM into the DVD-ROM drive.

   If the Volume Management daemon vold(1M) is running and configured to manage DVD-ROM devices, the daemon automatically mounts the DVD-ROM on the /cdrom directory.

3. Change to the CommonInstaller directory of the DVD-ROM.

   • If you are installing the data service packages on the SPARC® platform, type the following command:

     # cd /cdrom/cdrom0/Solaris_sparc

   • If you are installing the data service packages on the x86 platform, type the following command:

     # cd /cdrom/cdrom0/Solaris_x86

4. Start the CommonInstaller.

   # ./installer

5. When you are prompted, accept the license agreement.

   If any Sun Java Enterprise System components are installed, you are prompted to select whether to upgrade the components or install new software.

6. From the list of Sun Cluster agents under Availability Services, select the data service for Apache Tomcat.

7. If you require support for languages other than English, select the option to install multilingual packages.

   English language support is always installed.

8. When prompted whether to configure the data service now or later, choose Configure Later.

   Choose Configure Later to perform the configuration after the installation.

9. Follow the instructions on the screen to install the data service packages on the node.

   The CommonInstaller displays the status of the installation. When the installation is complete, the wizard displays an installation summary and the installation logs.

10. (GUI only) If you do not want to register the product and receive product updates, deselect the Product Registration option.

    The Product Registration option is not available with the CLI. If you are running the CommonInstaller with the CLI, omit this step

11. Exit the CommonInstaller.

12. Unload the Sun Java Availability Suite DVD-ROM from the DVD-ROM drive.

    1. To ensure that the DVD-ROM is not being used, change to a directory that does not reside on the DVD-ROM.

    2. Eject the DVD-ROM.

       # eject cdrom

Next Steps

See Registering and Configuring Sun Cluster HA for Apache Tomcat to register Apache Tomcat and to configure the cluster for the data service.

Registering and Configuring Sun Cluster HA for Apache Tomcat

This section contains the procedures you need to configure Sun Cluster HA for Apache Tomcat.

How to Register and Configure Sun Cluster HA for Apache Tomcat as a Failover Data Service

This procedure assumes that you installed the data service packages.

If you did not install the Sun Cluster HA for Apache Tomcat packages, go to Installing the Sun Cluster HA for Apache Tomcat Packages.

It is assumed that the file system of Apache Tomcat will be mounted as a failover file system.

1. Prepare the parameter file, which is required by the Sun Cluster HA for Apache Tomcat.

   # cd /opt/SUNWsctomcat/bin # cp pfile desired place

   Edit the parameter file pfile and follow the comments within that file. For example:

   #!/usr/bin/ksh # # Copyright 2006 Sun Microsystems, Inc. All rights reserved. # Use is subject to license terms. # #ident "@(#)pfile.ksh 1.2 06/03/08 SMI" # Set the Apache Tomcat specific environment variables which the start, stop # and check fuctions will use # # EnvScript Script to set runtime environment for tomcat # User Apache Tomcat User # Basepath Absolute path to Tomcat Home directory i.e. 4.x CATALINA_HOME # or TOMCAT_HOME for 3.x # Host Hostname to test Apache Tomcat # Port Port where Apache Tomcat is configured # TestCmd Apache Tomcat test command # Startwait Sleeping $Startwait seconds aftercompletion of the # start command EnvScript= User= Basepath= Host= Port=8080 TestCmd="get /index.jsp" ReturnString="CATALINA" Startwait=20

   The following is an example for Apache Tomcat 4.1.24.

   EnvScript=/global/mnt1/tomtest/env.ksh
   User=tomtest
   Basepath=/global/mnt1/tomtest/jakarta-tomcat-4.1.24
   Host=tomcat-lh
   Port=8080
   TestCmd="get /index.jsp"
   ReturnString="CATALINA"
   Startwait=20

   This example is from an Apache Tomcat 4.1.24 configured as standalone web server with the default start page index.jsp. The start page contains the string CATALINA.

   ---

   Caution –

   The parameter files need to be available on every node that can host the Apache Tomcat data service. For a failover configuration store them on the shared storage. The parameter files cannot differ for an instance of Apache Tomcat on the various nodes.

   ---

   Repeat Step 1 for every Apache Tomcat instance you need.

2. Create and register each required Apache Tomcat component.

   # cd /opt/SUNWsctomcat/util # cp sctomcat_config desired place

   Edit the sctomcat_config file and follow the comments within that file. For example:

   # # Copyright 2006 Sun Microsystems, Inc. All rights reserved. # Use is subject to license terms. # #ident "@(#)sctomcat_config.ksh 1.2 06/03/08 SMI" # This file will be sourced in by sctomcat_register and the parameters # listed below will be used. # # These parameters can be customized in (key=value) form # # RS - name of the resource for the application # RG - name of the resource group containing RS # PORT - name of the port number # LH - name of the LogicalHostname SC resource # SCALABLE - true for a scalable resource or false for a failover resource # NETWORK - false or true, false for multiple master configurations without # shared address, in this case SCALABLE will be ignored # # PFILE - absolute path to the parameter file for the Tomcat resource # HAS_RS - name of the HAStoragePlus SC resource # (it can be a , separated list for the dependencies) # # The following variables need to be set only if the agent runs in a # local zone # ZONE - the zone name where the Apache Tomcat should run in # Optional # ZONEBT - The resource name which controls the zone. # Optional # PROJECT - A project in the zone, that will be used for this service # specify it if you have an su - in the start stop or probe, # or to define the smf credentials. If the variable is not set, # it will be translated as :default for the smf manifest # Optional RS= RG= PORT= LH= NETWORK=false SCALABLE=false PFILE= HAS_RS= # local zone specific options ZONE= ZONE_BT= PROJECT=

   The following is an example for Apache Tomcat.

   RS=tomcat-res RG=tomcat-rg PORT=8080 LH=tomcat-lh SCALABLE=false PFILE=/global/mnt1/pfile NETWORK=true HAS_RS=tomcat-hastplus-res

3. After editing sctomcat_config register the resource.

   # ksh ./sctomcat_register -f desired place/sctomcat_config

   Repeat Step 9,10, and 11 for each Apache Tomcat instance you need.

4. Enable each Apache Tomcat resource.

   Repeat this step for each Apache Tomcat resource created in the step 10.

   # clresource status

   # clresource enable Apache-Tomcat-resource

How to Register and Configure Sun Cluster HA for Apache Tomcat as a Multiple Masters Data Service

This procedure assumes that you installed the data service packages during your initial Sun Cluster installation.

If you did not install the Sun Cluster HA for Apache Tomcat packages as part of your initial Sun Cluster installation, go to Installing the Sun Cluster HA for Apache Tomcat Packages.

1. Become superuser or assume a role that provides solaris.cluster.modify and solaris.cluster.admin RBAC authorizations.

2. Prepare the parameter file, which is required by the Sun Cluster HA for Apache Tomcat.

   # cd /opt/SUNWsctomcat/bin cp pfile desired place

   Edit the parameter file pfile and follow the comments within that file. For example:

   #!/usr/bin/ksh
   #
   # Copyright 2006 Sun Microsystems, Inc.  All rights reserved.
   # Use is subject to license terms.
   #
   
   #ident   "@(#)pfile.ksh 1.2     06/03/08 SMI"
   
   # Set the Apache Tomcat specific environment variables which the start, stop
   # and check fuctions will use
   #
   # EnvScript     Script to set runtime environment for tomcat
   # User          Apache Tomcat User
   # Basepath      Absolute path to Tomcat Home directory i.e. 4.x CATALINA_HOME
   #               or TOMCAT_HOME for 3.x
   # Host          Hostname to test Apache Tomcat
   # Port          Port where Apache Tomcat is configured
   # TestCmd       Apache Tomcat test command
   # Startwait     Sleeping $Startwait seconds aftercompletion of the
   #               start command
   EnvScript=
   User=
   Basepath=
   Host=
   Port=8080
   TestCmd="get /index.jsp"
   ReturnString="CATALINA"
   Startwait=20

   The following is an example for Apache Tomcat 4.1.24.

   EnvScript=/tomcat/env.ksh
   User=tomcat
   Basepath=/tomcat/jakarta-tomca-4.1.24
   Host=localhost
   Port=8080
   TestCmd="get /index.jsp"
   ReturnString="CATALINA"
   Startwait=20

   This example is from an Apache Tomcat 4.1.24 configured as standalone web server with the default start page index.jsp. The start page contains the string CATALINA.

   The Host parameter depends on the location of the pfile.

   • If the pfile is stored on the shared storage, you need to use localhost.

   • If the pfile is stored on the local storage, it can be either localhost or the nodes host name.

   ---

   Caution –

   The parameter files need to be available on every node that can host the Apache Tomcat data service. For a scalable or a multiple masters configuration, store them on the local file system of every node/none—global zone or on the shared storage. The parameter files must not differ for an instance of Apache Tomcat on the various nodes.

   ---

   Repeat this Step for every Apache Tomcat instance and every node you need.

3. Create and register each required Apache Tomcat component.

   # cd /opt/SUNWsctomcat/util # cp sctomcat_config desired place

   Edit the sctomcat_config file and follow the comments within that file, for example:

   # # Copyright 2006 Sun Microsystems, Inc. All rights reserved. # Use is subject to license terms. # #ident "@(#)sctomcat_config.ksh 1.2 06/03/08 SMI" # This file will be sourced in by sctomcat_register and the parameters # listed below will be used. # # These parameters can be customized in (key=value) form # # RS - name of the resource for the application # RG - name of the resource group containing RS # PORT - name of the port number # LH - name of the LogicalHostname SC resource # SCALABLE - true for a scalable resource or false for a failover resource # NETWORK - false or true, false for multiple master configurations without # shared address, in this case SCALABLE will be ignored # # PFILE - absolute path to the parameter file for the Tomcat resource # HAS_RS - name of the HAStoragePlus SC resource # (it can be a , separated list for the dependencies) # # The following variables need to be set only if the agent runs in a # local zone # ZONE - the zone name where the Apache Tomcat should run in # Optional # ZONEBT - The resource name which controls the zone. # Optional # PROJECT - A project in the zone, that will be used for this service # specify it if you have an su - in the start stop or probe, # or to define the smf credentials. If the variable is not set, # it will be translated as :default for the smf manifest # Optional RS= RG= PORT= LH= NETWORK=false SCALABLE=false PFILE= HAS_RS= # local zone specific options ZONE= ZONE_BT= PROJECT=

   The following is an example for Apache Tomcat.

   RS=tomcat-res RG=tomcat-rg PORT=8080 LH=tomcat-lh SCALABLE=false SNETWORK=falsePFILE=/local/pfile HAS_RS=Apache-Tomcat-has-resource

   Omit the LH parameter here, it will not be used. Set the parameter HAS_RS only when another file system (GFS or local file system) is used and the appropriate Apache-Tomcat-has-resource is created. The ZONE, ZONE_BT and PROJECT variables are needed only if the multiple masters container resources are zones managed by the container agent.

4. After editing sctomcat_config register the resource.

   # ksh ./sctomcat_register -f desired place/sctomcat_config

   Repeat Steps 7, 8, and 9 for every Apache Tomcat instance you need.

5. Enable each Apache Tomcat resource.

   Repeat this step for each Apache Tomcat resource created in the previous step.

   # clresource status

   # clresource enable Apache-Tomcat-resource

How to Register and Configure Sun Cluster HA for Apache Tomcat as a Scalable Data Service

This procedure assumes that you installed the data service packages during your initial Sun Cluster installation.

If you did not install the Sun Cluster HA for Apache Tomcat packages as part of your initial Sun Cluster installation, go to Installing the Sun Cluster HA for Apache Tomcat Packages.

1. Become superuser or assume a role that provides solaris.cluster.modify and solaris.cluster.admin RBAC authorizations.

2. Prepare the parameter file, which is required by the Sun Cluster HA for Apache Tomcat.

   # cd /opt/SUNWsctomcat/bin cp pfile desired place

   Edit the parameter file pfile and follow the comments within that file. For example:

   #!/usr/bin/ksh 
   # Set the Apache Tomcat specific environment variables which the start, 
   # stop and check functions will use 
   #
   # EnvScript     Script to set runtime environment for tomcat
   # User          Apache Tomcat user name
   # Basepath      Absolute pathname to Tomcat Home directory i.e. 4.x CATALINA_HOME
   #               or TOMCAT_HOME for 3.x
   # Host          Hostname to test Apache Tomcat 
   # Port          Port where Apache Tomcat is configured
   # TestCmd       Apache Tomcat test command
   # Startwait     Sleeping $Startwait seconds after completion of the 
   #               start command
   EnvScript=
   User=
   Basepath=
   Host=
   Port=8080
   TestCmd="get /index.jsp"
   ReturnString="CATALINA"
   Startwait=20

   The following is an example for Apache Tomcat 4.1.24.

   EnvScript=/tomcat/env.ksh
   User=tomcat
   Basepath=/tomcat/jakarta-tomca-4.1.24
   Host=localhost
   Port=8080
   TestCmd="get /index.jsp"
   ReturnString="CATALINA"
   Startwait=20

   This example is from an Apache Tomcat 4.1.24 configured as standalone web server with the default start page index.jsp. The start page contains the string CATALINA.

   The Host parameter depends on the location of the pfile.

   • If the pfile is stored on the shared storage, you need to use localhost.

   • If the pfile is stored on the local storage, it can be either localhost or the nodes host name.

   Do not use the SharedAddress here.

   ---

   Caution –

   The parameter files need to be available on every node that can host the Apache Tomcat data service. For a scalable or a multiple masters configuration, store them on the local file system of every node or on the shared storage. The parameter files must not differ for an instance of Apache Tomcat on the various nodes.

   ---

   Repeat this Step for every Apache Tomcat instance and every node you need.

3. Create and register each required Apache Tomcat component.

   # cd /opt/SUNWsctomcat/util # cp sctomcat_config desired place

   Edit the sctomcat_config file and follow the comments within that file, for example:

   # # Copyright 2006 Sun Microsystems, Inc. All rights reserved. # Use is subject to license terms. # #ident "@(#)sctomcat_config.ksh 1.2 06/03/08 SMI" # This file will be sourced in by sctomcat_register and the parameters # listed below will be used. # # These parameters can be customized in (key=value) form # # RS - name of the resource for the application # RG - name of the resource group containing RS # PORT - name of the port number # LH - name of the LogicalHostname SC resource # SCALABLE - true for a scalable resource or false for a failover resource # NETWORK - false or true, false for multiple master configurations without # shared address, in this case SCALABLE will be ignored # # PFILE - absolute path to the parameter file for the Tomcat resource # HAS_RS - name of the HAStoragePlus SC resource # (it can be a , separated list for the dependencies) # # The following variables need to be set only if the agent runs in a # local zone # ZONE - the zone name where the Apache Tomcat should run in # Optional # ZONEBT - The resource name which controls the zone. # Optional # PROJECT - A project in the zone, that will be used for this service # specify it if you have an su - in the start stop or probe, # or to define the smf credentials. If the variable is not set, # it will be translated as :default for the smf manifest # Optional RS= RG= PORT= LH= NETWORK=false SCALABLE=false PFILE= HAS_RS= # local zone specific options ZONE= ZONE_BT= PROJECT=

   The following is an example for Apache Tomcat.

   RS=tomcat-res RG=tomcat-rg PORT=8080 LH=tomcat-lh SCALABLE=true NETWORK=true PFILE=/tomcat/pfile HAS_RS=Apache-Tomcat-has-resource

   Configure the parameter LH need to be configured as the name of the shared address. Set the parameter HAS_RS only when another file system (GFS or local file system) is used and the appropriate Apache-Tomcat-has-resource is created.

4. After editing sctomcat_config register the resource.

   # ksh ./sctomcat_register desired place/sctomcat_config

   Repeat Steps 9, 10, an 11 for every Apache Tomcat instance you need.

5. Enable each Apache Tomcat resource.

   Repeat this step for each Apache Tomcat resource created in the previous step.

   #

   # clresource enable Apache-Tomcat-resource

Configuring Sun Cluster HA for Apache Tomcat in Zones

The Sun Cluster HA for Apache Tomcat can be configured in afailover zone and in a zone. This section describes the additional steps which are necessary to configure Sun Cluster HA for Apache Tomcat in both zone types.

Configuring Sun Cluster HA for Apache Tomcat in a Failover Zone

How to Register Sun Cluster HA for Apache Tomcat in a Failover Zone

This procedure uses the configuration file to register Sun Cluster HA for Apache Tomcat in a failover zone.

Before You Begin

Before you register Sun Cluster HA for Apache Tomcat in a failover zone, perform the following tasks. Follow procedures in the Sun Cluster Data Service for Solaris Containers Guide and Sun Cluster Data Service for Apache Tomcat Guide for Solaris OS.

• Install Sun Cluster HA for Containers and Sun Cluster HA for Apache Tomcat data-service packages in the global zone of each cluster node that you want to run the failover zone.

• Create the failover zone.

• Configure the boot component to control your failover zone.

1. Become superuser or assume a role that provides solaris.cluster.modify and solaris.cluster.admin RBAC authorizations.

2. Make a copy of the /opt/SUNWsctomcat/util/sctomcat_config file to use as your configuration file.

   You can place this configuration file in any directory that is accessible to the failover zone.

3. Open your configuration file for editing and modify the variables for non-global zones.

   These variables are used only when the data service is installed in a non-global zone. Set the values of these variables as follows:

   ZONE

   Set the name of the zone where Sun Cluster HA for Apache Tomcat should run.

   ZONE_BT

   Set the name of the resource that controls the zone.

   PROJECT

   Set the name of the Sun Resource Manager Project in the failover zone. If the PROJECT variable is omitted from the configuration file, the data service uses the default project of the user, :default, in a Solaris Service Management Facility (SMF) context. This project name is placed in the start/project property and the stop/project property of the SMF service.

   ---

   Note –

   Keep this modified configuration file for possible future use.

   ---

4. Register Sun Cluster HA for Apache Tomcat with SMF.

   # ksh /opt/SUNWsctomcat/util/sctomcat_register -f filename

   -f

   Specifies the configuration file name.

   filename

   The configuration file name.

   The registration of Sun Cluster HA for Apache Tomcat generates an SMF manifest and registers an SMF service in the failover zone that is specified by the ZONE variable in the configuration file. The manifest is named resourcename.xml, where resource is the name that is specified by the RS variable in the configuration file. This manifest is placed in the /var/svc/manifest/application/sczone-agents/ directory. The SMF service is named svc:/application/sczone-agents/resource.

   The Sun Cluster HA for Apache Tomcat data service uses the SMF component of the Sun Cluster HA for Containers data service to control and probe this SMF service of the Sun Cluster HA for Apache Tomcat. It registers a Sun Cluster HA for Containers SMF component on top of the already-created SMF service. The name of the script that starts and stops the manifest as well as probes the SMF component is control_sctomcat.

How to Modify Parameters in the Sun Cluster HA for Apache Tomcat Manifest

Perform this task to change parameters in the Sun Cluster HA for Apache Tomcat manifest and to validate the parameters in the failover zone. Parameters for the Sun Cluster HA for Apache Tomcat manifest are stored as properties of the SMF service. To modify parameters in the manifest, change the related properties in the SMF service then validate the parameter changes.

1. Become superuser or assume a role that provides solaris.cluster.modify and solaris.cluster.admin RBAC authorizations on the zones console.

2. Change the Solaris Service Management Facility (SMF) properties for the Sun Cluster HA for Apache Tomcat manifest.

   # svccfg svc:/application/sczone-agents:resource

   For more information, see the svccfg(1M) man page.

3. Validate the parameter changes.

   # /opt/SUNWsctomcat/bin/control_sctomcat validate resource

   Messages for this command are stored in the /var/adm/messages/ directory of the failover zone.

4. Disconnect from the failover zone's console.

How to Remove a Sun Cluster HA for Apache Tomcat Resource From a Failover Zone

1. Become superuser or assume a role that provides solaris.cluster.modify and solaris.cluster.admin RBAC authorizations.

2. Disable and remove the resource that is used by the Sun Cluster HA for Apache Tomcat data service.

   # clresource disable resource # clresource delete resource

3. Log in as superuser to the failover zone's console.

4. Unregister Sun Cluster HA for Apache Tomcat from the Solaris Service Management Facility (SMF) service.

   # /opt/SUNWsctomcat/util/sctomcat_smf_remove -f filename

   -f

   Specifies the configuration file name.

   filename

   The name of the configuration file that you used to register Sun Cluster HA for Apache Tomcat with the SMF service.

   ---

   Note –

   If you no longer have the configuration file that you used to register Sun Cluster HA for Apache Tomcat with the SMF service, create a replacement configuration file:

   1. Make a copy of the default file, /opt/SUNWsctomcat/util/sctomcat_config.

   2. Set the ZONE and RS parameters with the values that are used by the data service.

   3. Run the sctomcat_smf_remove command and use the -f option to specify this configuration file.

   ---

5. Disconnect from the failover zone's console.

Configuring Sun Cluster HA for Apache Tomcat in a Zone

How to Register Sun Cluster HA for Apache Tomcat in a Zone

This procedure uses the configuration file to register Sun Cluster HA for Apache Tomcat in a zone.

Before You Begin

Before you register Sun Cluster HA for Apache Tomcat in a zone, perform the following tasks. .

• Install Sun Cluster HA for Apache Tomcat data-service packages in the global zone of each cluster node that you want to run the zone.

• Create the zone on each node to host Sun Cluster HA for Apache Tomcat.

  ---

  Note –

  The zones configuration parameter autoboot must be set to true

  ---

1. Become superuser or assume a role that provides solaris.cluster.modify and solaris.cluster.admin RBAC authorizations.

2. Make a copy of the /opt/SUNWsctomcat/util/sctomcat_config file to use as your configuration file.

3. Open your configuration file for editing, but do not set the variables for non-global zones.

   These variables are used only when the data service is installed in a non-global zone managed by the Container Agent.

   ---

   Note –

   Keep this modified configuration file for possible future use.

   ---

4. Register Sun Cluster HA for Apache Tomcat with SMF.

   # ksh /opt/SUNWsctomcat/util/sctomcat_register -f filename

   -f

   Specifies the configuration file name.

   filename

   The configuration file name.

Verifying the Sun Cluster HA for Apache Tomcat Installation and Configuration

This section contains the procedure you need to verify that you installed and configured your data service correctly.

How to Verify the Sun Cluster HA for Apache Tomcat Installation and Configuration

1. Become superuser or assume a role that provides solaris.cluster.modify and solaris.cluster.admin RBAC authorizations.

2. Ensure all the Apache Tomcat resources are online with scstat.

   # cluster status

   For each Apache Tomcat resource which is not online, use the clresource command as follows.

   # clresource enable Apache Tomcat- resource

3. If you deployed a failover data service run the clresourcegroup command to switch the Apache Tomcat resource group to another cluster node, such as node2 or node2:zone1 with the command alternatives described below.

   # clresourcegroup switch -n node2 Apache-Tomcat-failover-resource-group

   # clresourcegroup switch -n node2:zone1 Apache-Tomcat-failover-resource-group

Understanding the Sun Cluster Apache Tomcat HA Parameter File

Use the information to understand the contents of the Sun Cluster Apache Tomcat HA parameter file. This section describes the structure and the content of the Sun Cluster Apache Tomcat HA parameter file, as well as the strategy to chose some of its variables.

Structure of the Apache Tomcat HA parameter file

Apache Tomcat HA uses a parameter file to pass parameters to the start, stop and probe command. This parameter file needs to be a valid Korn shell script which sets several variables. The structure of this file appears in Table 6. For examples of the parameter file refer to Registering and Configuring Sun Cluster HA for Apache Tomcat.

The parameters in Table 6 can be changed at any time. The only difference is when changes take effect.

The following parameters of the Apache Tomcat HA parameter file are used for starting and stopping Apache Tomcat. Changes to these parameters take effect at every restart or disabling and enabling of a Apache Tomcat resource.

• EnvScript

• User

• Basepath

• Startwait

The following parameters of the Apache Tomcat HA parameter file are used within the fault monitor. Changes to these parameters take effect at every Thorough_probe_interval.

• Host

• Port

• TestCmd

• ReturnString

Strategy to Chose the TestCmd and the ReturnString Variable

Alternatives are available to chose the ReturnString:

• Take the start page of your application and set the TestCmd to get /start_page. Set the ReturnString to a string contained in the startpage. With this strategy, you are monitoring that Apache Tomcat is serving your application.

• Take the Apache Tomcat default startpage and set the TestCmd to get /default-startpage. In this case, set the ReturnString to a string contained in the startpage. This string depends on the deployed Apache Tomcat version, for 3.x it is Tomcat home and for 4.x and 5.x it is CATALINA. With this strategy, you are monitoring that Apache Tomcat is serving its default application.

• Deploy a test application (which is not provided with the Sun Cluster Apache Tomcat agent) to Apache Tomcat. Set the TestCmd to get /startpage-of-the-application. In this case, set the ReturnString to a string contained in the startpage. With this strategy, you are monitoring that Apache Tomcat is serving your test application.

• If none of above is appropriate, set the TestCmd to get /a-page-which-does-not-exists. In this case, set the ReturnString to a string contained in the Error Page. With this strategy, you are monitoring that Apache Tomcat is operational, because it registers that it must deliver a page that does not exist.

You can evaluate the different pages by connecting using a browser with hostname:port and specifying the different pages.

Understanding Sun Cluster HA for Apache Tomcat Fault Monitor

This section describes the Sun Cluster HA for Apache Tomcat fault monitor's probing algorithm and functionality, states the conditions, messages, and recovery actions associated with unsuccessful probing, and states the conditions and messages associated with unsuccessful probing.

For conceptual information on fault monitors, see Sun Cluster Concepts Guide for Solaris OS.

Resource Properties

The Sun Cluster HA for Apache Tomcat fault monitor uses the same resource properties as the resource type SUNW.gds. Refer to the SUNW.gds(5) man page for a complete list of resource properties used.

Probing Algorithm and Functionality

The following steps are executed to monitor the sanity of Apache Tomcat.

1. Sleeps for Thorough_probe_interval.

2. Pings the Host, which is configured in the Apache Tomcat HA parameter file.

3. Connects to the Apache Tomcat via Host and Port. If the connection is successful it sends the TestCmd and tests whether the ReturnString comes back. If it fails, it is rescheduled after 5 seconds. If this fails again, then the probe will restart the Apache Tomcat.

   ---

   Caution –

   The ReturnString cannot be Connection refused because this string will be returned if no connection is possible.

   ---

4. If the Apache Tomcat process has died, pmf will interrupt the probe to immediately restart the Apache Tomcat.

5. If the Apache Tomcat is repeatedly restarted and subsequently exhausts the Retry_count within the Retry_interval, then a failover is initiated for the resource group onto another node. This is done if the resource property Failover_enabled is set to TRUE.

Debugging Sun Cluster HA for Apache Tomcat

Sun Cluster HA for Apache Tomcat has a file named config that enables you to activate debugging for Apache Tomcat resources. This file is in the /opt/SUNWsctomcat/etc directory.

How to Activate Debugging for Sun Cluster HA for Apache Tomcat

1. Determine whether you are in a global zone or in a failover zone configuration.

   If your operating system is Solaris 10 and your Apache Tomcat resource is dependent on a Solaris Container boot component resource, you are in a failover zone configuration. In any other case, especially on a Solaris r 9 system , you are in a global zone configuration.

2. Determine whether debugging for Sun Cluster HA for Apache Tomcat is active.

   # grep daemon /etc/syslog.conf *.err;kern.debug;daemon.notice;mail.crit /var/adm/messages *.alert;kern.err;daemon.err operator #

   If debugging is inactive, daemon.notice is set in the file /etc/syslog.conf of the appropriate zone.

3. If debugging is inactive, edit the /etc/syslog.conf file in the appropriate zone to change daemon.notice to daemon.debug.

4. Confirm that debugging for Sun Cluster HA for Apache Tomcat is active.

   If debugging is active, daemon.debug is set in the file /etc/syslog.conf.

   # grep daemon /etc/syslog.conf *.err;kern.debug;daemon.debug;mail.crit /var/adm/messages *.alert;kern.err;daemon.err operator #

5. Restart the syslogd daemon in the appropriate zone.

   • If your operating system is Solaris 9, type:

     # pkill -1 syslogd

   • If your operating system is Solaris 10, type:

     # svcadm refresh svc:/system/system-log:default

6. Edit the /opt/SUNWsczone/sczbt/etc/config file to change the DEBUG= variable according to one of the examples:

   • DEBUG=ALL

   • DEBUG=resource name

   • DEBUG=resource name,resource name, ...

   # cat /opt/SUNWscPostgreSQL/etc/config # # Copyright 2006 Sun Microsystems, Inc. All rights reserved. # Use is subject to license terms. # # Usage: # DEBUG=<RESOURCE_NAME> or ALL # DEBUG=ALL #

   ---

   Note –

   To deactivate debugging, repeat step 1 to 6, changing daemon.debug to daemon.notice and changing the DEBUG variable to DEBUG=.

   ---