Installing and Configuring Sun Cluster HA for Sun Java System Message Queue

This chapter describes the procedures to install and configure the Sun Cluster HA for Sun Java System Message Queue.

This chapter contains the following sections.

• Sun Cluster HA for Sun Java System Message Queue Overview

• Overview of the Installation and Configuration Process for Sun Cluster HA for Sun Java System Message Queue

• Planning the Sun Java System Message Queue Installation and Configuration

• Configuring and Activating Network Resources

• Installing and Configuring the Sun Java System Message Queue

• Verifying the Sun Java System Message Queue Installation and Configuration

• Planning the Sun Cluster HA for Sun Java System Message Queue Installation and Configuration

• Installing the Sun Cluster HA for Sun Java System Message Queue Package

• Registering and Configuring the Sun Cluster HA for Sun Java System Message Queue

• Configuring the SUNW.HAStoragePlus Resource Type

• Verifying the Sun Cluster HA for Sun Java System Message Queue Installation and Configuration

• Tuning the Sun Cluster HA for Sun Java System Message Queue Fault Monitor

Sun Cluster HA for Sun Java System Message Queue Overview

Use the information in this section to understand how the Sun Cluster HA for Sun Java System Message Queue enables the Sun Java System Message Queue for high availability.

The Sun Cluster HA for Sun Java System Message Queue is a data service with appropriate extension properties to configure a failover messaging service.

Configure the Sun Cluster HA for Sun Java System Message Queue as a failover data service to enable the Sun Java System Message Queue for high availability. See Chapter 1, Planning for Sun Cluster Data Services, in Sun Cluster Data Services Planning and Administration Guide for Solaris OS for general information about data services.

The Sun Java System Message Queue is an integral part of the application server. The Sun Java System Message Queue is a robust Java Messaging Service (JMS) provider for JMS clients. The Sun Java System Message Queue is packaged with the Sun Java System Application Server installation. Refer to Sun Java System Message Queue documentation for information about the Sun Java System Message Queue. Implementation of the Sun Cluster HA for Sun Java System Message Queue does not assume the existence of programs on which your architecture depends. Programs on which your architecture depends such as databases and web servers should be configured to be highly available, but might run on a different cluster.

Overview of the Installation and Configuration Process for Sun Cluster HA for Sun Java System Message Queue

The following table lists the sections that describe the installation and configuration tasks. Perform these tasks in the order that they are listed.

If you run multiple data services in your Sun Cluster configuration, you can set up the data services in any order, with the following exception. If the Sun Cluster HA for Sun Java System Message Queue depends on the Sun Cluster HA for DNS, you must set up DNS first. For details, see Sun Cluster Data Service for DNS Guide for Solaris OS for details. DNS software is included in the Solaris operating environment. If the cluster is to obtain the DNS service from another server, configure the cluster to be a DNS client first.

Planning the Sun Java System Message Queue Installation and Configuration

To install and configure the Sun Java System Message Queue, use this section as a checklist in conjunction with the worksheets in the Configuration Worksheets in Sun Cluster Data Services Planning and Administration Guide for Solaris OS.

Consider the following before you start your installation. Store static files and data on the local file system of each cluster node. Dynamic data should reside on the cluster file system so that you can view or update the data from any cluster node. The Sun Java System Message Queue binaries and configuration files must be highly available and accessible to application-server instances that are running on all nodes.

Configuring and Activating Network Resources

Before you install and configure the Sun Java System Message Queue, set up the network resources that the service uses after installation and configuration. To configure and activate the network resources, use the following command-line procedure.

How to Configure and Activate Network Resources

To perform this procedure, you need the following information about your configuration.

• The names of the cluster nodes that can master the data service.

• The network resource that clients use to access the Sun Java System Message Queue. Normally, you set up this hostname when you install the cluster. See the Sun Cluster Concepts Guide for Solaris OS for details on network resources.

Steps

1. Become superuser on a cluster member.

2. Verify that all of the network addresses that you use have been added to your name service database.

   You should have performed this verification during the Sun Cluster installation.

   ---

   Note –

   To avoid name service look-up failures, ensure that all of the logical hostnames are present in the /etc/inet/hosts file on all of the cluster nodes. Configure name service mapping in the /etc/nsswitch.conf file on the servers to check the local files before trying to access NIS, NIS+, or DNS.

   ---

3. Create a failover resource group to contain the network and application resources.

   # scrgadm -a -g resource-group [-h nodelist]

   -g resource-group

   Specifies the name of the resource group. This name can be your choice.

   [-h nodelist]

   Specifies an optional comma-separated list of physical node names for the Sun Java System Message Queue that identify potential masters. The order here determines the order in which the nodes are considered primary during failover.

   ---

   Note –

   Use the -h option to specify the order of the node list. If all of the nodes in the cluster are potential masters, you do not need to use the -h option.

   ---

4. Add network resources to the resource group.

   Use the following command to add a logical hostname to a resource group.

   # scrgadm -a -L -g resource-group -l hostname, …[-n netiflist]

   -L

   Specifies that a network resource is being added.

   -g resource-group

   Specifies the name of the resource group.

   -l hostname, …

   Specifies a comma-separated list of network resources.

   -n netiflist

   Specifies an optional, comma-separated list that identifies the IP Networking Multipathing groups that are on each node. Each element in netiflist must be in the form of netif@node. netif can be given as an IP Networking Multipathing group name, such as sc_ipmp0. The node can be identified by the node name or node ID, such as sc_ipmp0@1 or sc_ipmp@phys-schost-1.

   ---

   Note –

   Sun Cluster does not currently support the use of the adapter name for netif.

   ---

5. Run the scswitch command to enable the resource group and bring the resource group online.

   # scswitch -Z -g resource-group

   -Z

   Moves the resource group to the MANAGED state and brings the resource group online.

   -g resource-group

   Specifies the name of the resource group.

Installing and Configuring the Sun Java System Message Queue

The Sun Java System Message Queue is a Java 2 Enterprise Edition (J2EE™) 1.3 compliant messaging service. This queue is designed to meet the needs of enterprise customers and run under the control of Sun Cluster software. This section describes the steps to install and enable the Sun Java System Message Queue to run as the Sun Cluster HA for Sun Java System Message Queue.

If you run the Sun Java System Message Queue and another messaging service server and they use the same network resources, configure them to listen on different ports. Otherwise, a port conflict might occur between the two services.

Use the following procedure to install the Sun Java System Message Queue.

How to Install the Sun Java System Message Queue

Use the following procedure to install the Sun Java System Message Queue. Only the sections that are specific to the Sun Java System Message Queue are included here. See the Sun Java System Message Queue for Solaris OS documentation for details.

Do not set the AUTOSTART property to YES in the /etc/imq/imqbrokerd.conf file. The AUTOSTART property is set to NO by default because Sun Cluster HA for Sun Java System Message Queue starts and stops the application after you have configured the data service.

Steps

1. Install the Sun Java System Message Queue package on all the nodes of the cluster if they are not already installed.

2. Identify a location on a global file system where you intend to keep your message queue (for example, /global/s1mq).

   You can create a separate directory for this file system.

3. On any node set IMQ_VARHOME and run the imqbrokerd command to create the configuration directory and files.

   # IMQ_VARHOME=/global/s1mq # export IMQ_VARHOME # imqbrokerd -name hamq1

4. Set the imq.jms.tcp.hostname property to the logical hostname by editing $IMQ_VARHOME/instances/hamq1/props/config.properties.

Verifying the Sun Java System Message Queue Installation and Configuration

This section describes how to verify the Sun Java System Message Queue installation and configuration.

How to Verify the Sun Java System Message Queue Installation and Configuration

Use this procedure to verify the Sun Java System Message Queue installation and configuration. This procedure does not verify that your application is highly available.

Steps

1. Ensure that the logical hostname is running.

2. Set IMQ_VARHOME and start the message broker manually:

   # IMQ_VARHOME=/global/s1mq # export IMQ_VARHOME # imqbrokerd -name hamq1

3. Stop the broker.

   # /usr/bin/imqcmd shutdown bkr -b hostname:port

4. Repeat Step 2 on all of the potential primaries of the Sun Java System Message Queue resource group.

Planning the Sun Cluster HA for Sun Java System Message Queue Installation and Configuration

This section contains the information that you need to plan your Sun Cluster HA for Sun Java System Message Queue installation and configuration.

Standard Data Service Configurations

Use the standard configurations in this section to plan the installation and configuration of the Sun Cluster HA for Sun Java System Message Queue. The Sun Cluster HA for Sun Java System Message Queue might support additional configurations. However, you must contact your Enterprise Services representative for information on additional configurations.

The following figure illustrates a standard failover configuration for the Sun Java System Message Queue.

Figure 1 Two-Node Cluster with Failover Data Service Configuration

Configuration Considerations

If you choose to use your message service with another highly available application, resource dependencies might exist. See Appendix A, Standard Properties, in Sun Cluster Data Services Planning and Administration Guide for Solaris OS for a description of the Resource_dependencies property.

Configuration Planning Questions

Use the questions in this section to plan the installation and configuration of the Sun Cluster HA for Sun Java System Message Queue. See Considerations for Installing and Configuring a Data Service in Sun Cluster Data Services Planning and Administration Guide for Solaris OS for information that might apply to these questions.

• What resource groups will you use for network addresses and application resources and the dependencies between them?

• What is the logical hostname (for failover services) for clients that will access the data service?

• Where will the system configuration files reside?

Installing the Sun Cluster HA for Sun Java System Message Queue Package

If you did not install the Sun Cluster HA for Sun Java System Message Queue package during your initial Sun Cluster installation, perform this procedure to install the package. Perform this procedure on each cluster node where you are installing the Sun Cluster HA for Sun Java System Message Queue package.

If you are installing more than one data service simultaneously, perform the procedure in Installing the Software in Sun Cluster Software Installation Guide for Solaris OS.

If you are using Solaris 10, install these packages only in the global zone. To ensure that these packages are not propagated to any local zones that are created after you install the packages, use the scinstall utility to install these packages. Do not use the Sun Java Enterprise System Common Installer program.

How to Install the Sun Cluster HA for Sun Java System Message Queue Package by Using the scinstall Utility

Perform this procedure on all of the cluster members that can master Sun Cluster HA for Sun Java System Message Queue.

Before You Begin

Ensure that you have the Sun Cluster Agents CD.

Steps

1. Load the Sun Cluster Agents CD into the CD-ROM drive.

2. Run the scinstall utility with no options.

   This step starts the scinstall utility in interactive mode.

3. Select the menu option, Add Support for New Data Service to This Cluster Node.

   The scinstall utility prompts you for additional information.

4. Provide the path to the Sun Cluster Agents CD.

   The utility refers to the CD as the “data services cd.”

5. Specify the data service to install.

   The scinstall utility lists the data service that you selected and asks you to confirm your choice.

6. Exit the scinstall utility.

7. Unload the CD from the drive.

How to Install the Sun Cluster HA for Sun Java System Message Queue Package by Using the Sun Java Enterprise System Common Installer Program

You can run the Sun Java Enterprise System Common Installer program 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.

To complete this procedure, you need the Sun Java Enterprise System Common Installer CD-ROM.

Steps

1. On the cluster node where you are installing the Sun Cluster HA for Sun Java System Message Queue package, become superuser.

2. (Optional) If you intend to run the Sun Java Enterprise System Common Installer program with a GUI, ensure that your DISPLAY environment variable is set.

3. Load the Sun Java Enterprise System Common Installer CD-ROM into the CD-ROM drive.

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

4. Change to the Sun Java Enterprise System Common Installer directory of the CD-ROM.

   # cd /cdrom/Solaris_sparc

5. Start the Sun Java Enterprise System Common Installer program.

   # ./installer

6. When you are prompted, accept the license agreement and appropriate language support.

   English language support is available by default.

7. Select Sun Cluster Agents for Sun Java System under the Availability Services & Sun Cluster 3.1 Subcomponents and proceed.

   This selection includes all the available Sun Cluster data services for Sun Java System applications, including the Sun Cluster HA for Sun Java System Message Queue.

8. When you are prompted for the time of the configuration, choose Configure Later.

   Specify Configure Later in order to perform the configuration after the installation.

9. (Optional) If you do not want to register the product and receive product updates, uncheck the Product Registration box.

10. Follow the instructions on the screen to install the Sun Cluster HA for Sun Java System Message Queue package on the node.

    The Sun Java Enterprise System Common Installer program displays the status of the installation. When the installation is complete, the program displays an installation summary and the installation logs.

11. Exit the Sun Java Enterprise System Common Installer program.

    Before exiting the installer program, ensure that the Sun Cluster HA for Sun Java System Message Queue has been installed successfully. Check for the presence of the package by executing the following command:

    # pkginfo -l SUNWscs1mq

12. Unload the Sun Java Enterprise System Common Installer CD-ROM from the CD-ROM drive.

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

    2. Eject the CD-ROM.

       # eject cdrom

Registering and Configuring the Sun Cluster HA for Sun Java System Message Queue

This procedure describes how to use the scrgadm command to register and configure the Sun Cluster HA for Sun Java System Message Queue.

See Tools for Data Service Resource Administration in Sun Cluster Data Services Planning and Administration Guide for Solaris OS for details about additional options that enable you to register and configure the data service.

To perform this procedure, you need the following information about your configuration.

• The name of the resource type for the Sun Cluster HA for Sun Java System Message Queue is SUNW.s1mq.

• The names of the cluster nodes that can master the data service.

• The network resource that clients use to access the Sun Cluster HA for Sun Java System Message Queue.

• The port where the Sun Java System Message Queue listens.

Setting Sun Cluster HA for Sun Java System Message Queue Extension Properties

The section that follows contains instructions for registering and configuring Sun Cluster HA for Sun Java System Message Queue resources. For information about the extension properties, see Appendix A, Sun Cluster HA for Sun Java System Message Queue Extension Properties. The Tunable entry indicates when you can update a property.

See Appendix A, Standard Properties, in Sun Cluster Data Services Planning and Administration Guide for Solaris OS for details on all of the Sun Cluster properties.

To set an extension property of a resource, include the following option in the scrgadm(1M) command that creates or modifies the resource:

-x property=value 

-x property

Identifies the extension property that you are setting

value

Specifies the value to which you are setting the extension property

You can also use the procedures in Chapter 2, Administering Data Service Resources, in Sun Cluster Data Services Planning and Administration Guide for Solaris OS to configure resources after the resources are created.

How to Register and Configure the Sun Cluster HA for Sun Java System Message Queue as a Failover Data Service

Perform the following steps to complete your configuration.

Steps

1. Become superuser on a cluster member.

2. Add the resource group for the Sun Java System Message Queue if you have not performed the steps in Configuring and Activating Network Resources.

   # scrgadm -a -g resource group [-h nodelist]

3. Add the logical hostname resource to the resource group if you have not performed the steps in Configuring and Activating Network Resources.

   # scrgadm -a -L -g resource group -l logical hostname

4. Register the resource type for the data service.

   # scrgadm -a -t SUNW.s1mq

   -a

   Adds the data service resource type

   -t SUNW.s1mq

   Specifies the predefined resource type name

5. If the Smooth_Shutdown extension property is set to TRUE, create a file named scs1mqconfig in the $IMQ_VARHOME/instances/broker/ directory. Add the following line to the file you created:

   Password password

   See Appendix A, Sun Cluster HA for Sun Java System Message Queue Extension Properties for a description of the Smooth_Shutdown extension property.

6. Add the Sun Java System Message Queue resource instance to the failover resource group.

   [If Smooth_Shutdown will be set to FALSE (the default):] # scrgadm -a -j resource -g resource-group -t SUNW.s1mq \ -x Confdir_list=$IMQ_VARHOME/instances/broker \ -x Broker_Name=broker \ -y Network_Resources_Used=logical hostname \ -y Port_list=port/tcp[,port/tcp]

   [If Smooth_Shutdown is set to TRUE:] # scrgadm -a -j resource -g resource-group -t SUNW.s1mq \ -x Confdir_list=$IMQ_VARHOME/instances/broker \ -x Broker_Name=broker \ -x Broker_User=user \ -y Network_resources_used=logical hostname \ -y Port_list=port/tcp[,port/tcp] \ -x Smooth_Shutdown=TRUE

   The resource group that contains the application resources is the same resource group that you created for your network resources in How to Configure and Activate Network Resources.

   -j resource

   Specifies the Sun Java System Message Queue application resource name.

   -t SUNW.s1mq

   Specifies the type of resource to add.

   -x Confdir_list=$IMQ_VARHOME/instances/broker

   Specifies a path for your Sun Java System Message Queue configuration directory. The Confdir_list extension property is required. The Confdir_list property must have exactly one entry.

   -x Broker_Name=broker

   Specifies the name of the broker to monitor.

   -x Broker_User=user

   Specifies the user name of the managed broker.

   -y Network_resources_used=network-resource

   Specifies a comma-separated list of network resources (logical hostnames) in resource-group, which the Sun Java System Message Queue application resource must use.

   -y Port_list=port-number/protocol

   Specifies a port number and the protocol to be used, for example, 80/tcp. The Port_list property must have one or two entries.

   -x Smooth_Shutdown=TRUE

   Used to shutdown the broker. Use of the impcmd command exposes the broker password in the imqcmd command string.

7. Bring the resource group online.

   # scswitch -Z -g resource-group

   -Z

   Enables the resource and its monitor.

   -g resource-group

   Specifies the name of the application resource group that is being enabled.

8. Verify that the resource group and application-server resource is online.

   # scstat -g # ps -ef

Example 1 Registering and Configuring the Sun Cluster HA for Sun Java System Message Queue

This example shows how to register the Sun Cluster HA for Sun Java System Message Queue.

Cluster Information
Node names: phys-schost-1, phys-schost-2
Logical hostname: schost-1
Resource group: resource-group-1 (for all resources)
Resources: schost-1 (logical hostname),
SUNW.s1mq (Sun Java System Message Queue application resource) 
 
(Create a failover resource group.)
# scrgadm -a -g resource-group-1 -h phys-schost-1,phys-schost-2
 
(Add a logical hostname resource to the resource group.)
# scrgadm -a -L -g resource-group-1 -l schost-1
 
(Register the SUNW.s1mq resource type.)
# scrgadm -a -t SUNW.s1mq
 
(Create a Sun Java System Message Queue resource and add it to the 
resource group.)
# scrgadm -a -j s1mq-rs -g s1mq-rg \
-t SUNW.s1mq \
-x Confdir_list=$IMQ_VARHOME/instances/hamq1 \
-x Broker_Name=hamq1 \
-y Network_resources_used=schost-1 \
-y Port_list=7676/tcp

 (Enable the application resource group.)
# scswitch -Z -g s1mq-rg

Example 2 Registering and Configuring Sun Cluster HA for Sun Java System Message Queue With Smooth_Shutdown Enabled

This example shows how to register Sun Cluster HA for Sun Java System Message Queue with Smooth_Shutdown enabled.

Cluster Information
Node names: phys-schost-1, phys-schost-2
Logical hostname: schost-1
Resource group: resource-group-1 (for all resources)
Resources: schost-1 (logical hostname),
	s1mq-1 (Sun Java System Message Queue application resource) 
 
(Create a failover resource group.)
# scrgadm -a -g resource-group-1 -h phys-schost-1,phys-schost-2
 
(Add a logical hostname resource to the resource group.)
# scrgadm -a -L -g resource-group-1 -l schost-1
 
(Register the SUNW.s1mq resource type.)
# scrgadm -a -t SUNW.s1mq
 
(Create a Sun Java System Message Queue resource and add it to the 
resource group.)
# scrgadm -a -j s1mq-rs -g s1mq-rg \
-t SUNW.s1mq \
-x Confdir_list=$IMQ_VARHOME/instances/hamq1 \
-x Broker_Name=hamq1 \
-x Broker_User=admin \
-y Network_resources_used=schost-1 \
-y Port_list=7676/tcp \
-x Smooth_Shutdown=TRUE
 
(Enable the application resource group.)
# scswitch -Z -g s1mq-rg

Configuring the SUNW.HAStoragePlus Resource Type

The SUNW.HAStoragePlus resource type was introduced in Sun Cluster 3.0 5/02. This new resource type performs the same functions as SUNW.HAStorage, and synchronizes actions between HA storage and the data service.

SUNW.HAStoragePlus also has an additional feature to make a local file system highly available. Sun Cluster HA for Sun Java System Message Queue is not disk intensive and not scalable, and therefore setting up the SUNW.HAStoragePlus resource type is optional.

See the SUNW.HAStoragePlus(5) man page and Relationship Between Resource Groups and Disk Device Groups in Sun Cluster Data Services Planning and Administration Guide for Solaris OS for background information. See Synchronizing the Startups Between Resource Groups and Disk Device Groups in Sun Cluster Data Services Planning and Administration Guide for Solaris OS for the procedure. If you are using a Sun Cluster 3.0 version prior to 5/02, you must set up SUNW.HAStorage instead of SUNW.HAStoragePlus.

Verifying the Sun Cluster HA for Sun Java System Message Queue Installation and Configuration

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

How to Verify the Sun Cluster HA for Sun Java System Message Queue Installation and Configuration

Use this procedure to verify that you installed and configured the Sun Cluster HA for Sun Java System Message Queue correctly.

Steps

1. Ensure that the Message Queue is started under the control of Sun Cluster software.

   # scswitch -Z -g resource group

2. Connect to the Sun Java System Message Queue from a web browser to verify that the Sun Java System Message Queue software functions correctly.

3. Run the scswitch command to switch the resource group to another cluster node, such as node2.

   # scswitch -z -g resource-group -h node2

4. Verify that the resource group and message queue resource is online.

   # scstat -g # ps -ef

5. Repeat Step 2 through Step 4 on all of the potential primaries of the Sun Java System Message Queue resource groups.

Tuning the Sun Cluster HA for Sun Java System Message Queue Fault Monitor

The Sun Cluster HA for Sun Java System Message Queue fault monitor is contained in the resource that represents Sun Java System Message Queue. You create this resource when you register and configure Sun Cluster HA for Sun Java System Message Queue. For more information, see Registering and Configuring the Sun Cluster HA for Sun Java System Message Queue.

System properties and extension properties of this resource control the behavior of the fault monitor. The default values of these properties determine the preset behavior of the fault monitor. The preset behavior should be suitable for most Sun Cluster installations. Therefore, you should tune the Sun Cluster HA for Sun Java System Message Queue fault monitor only if you need to modify this preset behavior.

For more information, see the following sections.

• Tuning Fault Monitors for Sun Cluster Data Services in Sun Cluster Data Services Planning and Administration Guide for Solaris OS

• Changing Resource Type, Resource Group, and Resource Properties in Sun Cluster Data Services Planning and Administration Guide for Solaris OS

• Appendix A, Standard Properties, in Sun Cluster Data Services Planning and Administration Guide for Solaris OS

Operations by the Fault Monitor During a Probe

The Sun Cluster HA for Sun Java System Message Queue fault monitor uses the Smooth_shutdown extension property. For instructions on setting this property, see Setting Sun Cluster HA for Sun Java System Message Queue Extension Properties.

The Sun Cluster HA for Sun Java System Message Queue probe sends a request to the server to query the health of the Sun Java System Message Queue server instance.

The probe connects to the IP address and port combinations defined by the network resource configuration and the Port_list setting for the resource group. If the connection succeeds, the probe reads the port mapper information. Finally the probe disconnects. If any part of the connection fails, a failure is recorded.

Heavy network traffic, heavy system load, and misconfiguration can cause the query to fail. Misconfiguration can occur if you did not configure the Sun Java System Message Queue server to listen on all of the IP address and port combinations that are probed. The Sun Java System Message Queue server should service every port for every IP address that is specified for this resource.

When the probe fails to connect to the server, a complete probe failure occurs. The following error message is sent, where the %s indicates the hostname and %d indicates the port number.

Failed to connect to the host <%s> and port <%d>.

The probe accumulates partial failures that happen within the resource property interval Retry_interval until they equal a complete failure that requires action.

The following are partial probe failures.

• Failure to disconnect. The following error message is sent, where %d indicates the port number and %s indicates the resource name.

  Failed to disconnect from port %d of resource %s.

• Failure to complete all probe steps within Probe_timeout time.

• Failure to read data from the server for other reasons. The following error message is sent, where the first %s indicates the hostname, %d indicates the port number, and the second %s indicates further details about the error.

  Failed to communicate with server %s port %d: %s

Based on the history of failures, a failure can cause either a local restart or a failover of the data service.