Configuring Instant Messaging for High Availability (Solaris Only)

Configuring Instant Messaging for high availability (HA) provides for monitoring of and recovery from software and hardware failures. The high availability feature is implemented as a failover data service, not a scalable service, and is supported on Solaris only. This chapter describes an Instant Messaging HA configuration using Sun Cluster software. See HA Related Documentation for more information about scalable and failover data services provided by Sun Cluster.

This chapter describes how to configure an Instant Messaging HA service, including:

Instant Messaging HA Overview

You use Sun Cluster with Instant Messaging to create a highly available deployment. This section provides information about HA requirements, terms used in examples in this chapter, and permissions you need to configure HA in the following sections:

• Instant Messaging HA Configuration Software Requirements
• Instant Messaging HA Configuration Permission Requirements
• Instant Messaging HA Configuration Terms and Checklist

Before you begin, you should be familiar with general HA concepts, and Sun Cluster software in particular. For more information, see HA Related Documentation.

Instant Messaging HA Configuration Software Requirements

An Instant Messaging HA configuration requires the software shown in Table 4-1.

Table 4-1 Software Requirements for Instant Messaging HA Configuration

Instant Messaging HA Configuration Permission Requirements

To install and configure an Instant Messaging HA configuration, log in as or become superuser (root) and specify a console or window for viewing messages sent to /dev/console.

Instant Messaging HA Configuration Terms and Checklist

Table 4-2 describes the variable terms used in the examples in this chapter for configuration examples. In addition, you will need to gather the information before you configure HA for Instant Messaging. You will be prompted for this information during configuration. Use this checklist in conjunction with the checklist in Table 1-1.

Table 4-2 HA Configuration Checklist

Top

Setting Up HA for Instant Messaging

The following is a high-level list of the steps necessary to install and configure an Instant Messaging HA configuration with two nodes:

• Choosing a Local or Shared Disk for Configuration Files and Binaries
• Preparing Each Node in the Cluster
• Selecting the Installation Directory (im-svr-base)
• Installing Sun Java System Products and Packages
• Configuring the HA Environment
• Configuring the Logical Host
• Registering and Activating the Storage Resource
• Registering the Resource Type and Creating a Resource
• Verifying the Instant Messaging HA Configuration
• Troubleshooting the Instant Messaging HA Configuration

Choosing a Local or Shared Disk for Configuration Files and Binaries

Before you begin, you need to decide which of the following deployments best suits your needs. In both environments, shared components are installed locally on every node in the cluster. In addition, in both environments, runtime files are installed on a shared disk.

• Using a local disk for configuration files and binaries. The advantage to this setup is that upgrading Instant Messaging requires minimal downtime because you can upgrade on nodes where Instant Messaging is offline. The disadvantage is that you need to ensure that the same configuration and version of Instant Messaging exists on all nodes in the cluster.
  In addition, if you choose this option, you need to determine whether you will be using HAStoragePlus to mount a file system from a shared disk on each node when Instant Messaging data services are brought online, or if you will be using the cluster file system for global runtime files.
• Using a shared disk for configuration files and binaries. This setup is easier to administer, but you need to bring Instant Messaging down on all nodes in the cluster before upgrading.

Preparing Each Node in the Cluster

On each node in the cluster, you need to create the Instant Messaging runtime user and group under which the components will run. The UID and GID numbers must be the same on all nodes in the cluster.

• Runtime User ID. The user name under which Instant Messaging server runs. This name should not be root. The default is inetuser.
• Runtime Group ID. The group under which Instant Messaging server runs. The default is inetgroup.

Although the configure utility can create these names for you, you can create them before you run the configuration program, as part of the preparation of each node as described in this chapter. In addition, depending on whether you are using a local or shared disk, you may not run configure on a particular node and must manually create the runtime user and group ID.

The runtime user and group ID names must be in the following files:

• inetuser, or the name you select, in /etc/passwd on all nodes in the cluster
• inetgroup, or the name you select, in /etc/group on all nodes in the cluster

See [Creating a UNIX System User and Group] for instructions. Refer to your operating system documentation for detailed information about users and groups.

Selecting the Installation Directory (im-svr-base)

For Instant Messaging, the Java Enterprise System installer uses /opt/SUNWiim on Solaris as the default installation directory (im-svr-base). However, if you are using a shared disk for configuration files and binaries, you must specify a global (shared) installation directory. For example: /global/im/opt/SUNWiim.

If you are using a local disk, you can install Instant Messaging to the default directory. However, you should Install Instant Messaging in the same directory on each machine in the node.

Installing Sun Java System Products and Packages

You install products and packages using the Communications Suite installer program. For more information about the installer, refer to the http://docs.sun.com/doc/819-7560.

Table 4-3 lists the products or packages required for a multiple node cluster configuration.

Table 4-3 Products and Packages Required for a Multiple Node Instant Messaging HA Configuration

Configuring the HA Environment

The steps you need to perform vary depending on whether or not you are using a local or shared disk for configuration files and binaries.

If you are using a local disk for configuration files and binaries, follow the steps in the following two procedures:

• To Configure HA on Node 1 Using a Local Disk for Configuration Files and Binaries
• To Configure HA on Node n Using a Local Disk for Configuration Files and Binaries

If you are using a shared disk for configuration files and binaries, follow the steps in the following two procedures:

• To Configure HA on Node 1 Using a Shared Disk for Configuration Files and Binaries
• To Configure HA on Node n Using a Shared Disk for Configuration Files and Binaries

To Configure HA on Node 1 Using a Local Disk for Configuration Files and Binaries Before You Begin

Fill out the checklists in Table 1-1 and Table 4-2 and have your answers readily available.

1. Install products and packages using the Java Enterprise System installer.
   See Selecting the Installation Directory (im-svr-base) for specific instructions on choosing an installation directory.
   See Table 4-3 for a list of required products and packages for HA. Refer to the http://docs.sun.com/doc/819-7560 for specific instructions.
2. If you are using HAStoragePlus for the runtime files, mount a shared disk to a local directory, otherwise skip to Step 3.
   For example:
3. Create the mount point (/local/im/im-runtime-base/) if it does not already exist.
   When prompted during configuration in Step 4 you will specify this directory (/local/im/im-runtime-base/) as the Instant Messaging Server Runtime Files Directory.
4. Use the mount command to mount the disk on /local/im/im-runtime-base.
5. Run the configure utility.
   See Chapter 1 Configuring Instant Messaging After Installation for instructions.
6. When prompted for the Instant Messaging Server Runtime Files Directory, enter one of the following:

• If you are using an HAStoragePlus for the runtime files, enter /local/im/im-runtime-base/.
• If you are using a cluster file system for the runtime files, enter /global/im/im-runtime-base/. Where /global/im is the global directory in the cluster file system.

1. When prompted for the Instant Messaging host name, enter the logical host.
   Choose to accept the logical host even if the configure utility cannot connect to the specified host. The logical host resource may be offline at the time you run the configure utility.
2. Do not choose to start Instant Messaging after configuration or on system startup.
   In an HA configuration, the Instant Messaging service also requires the logical host to be online for Instant Messaging to work properly.
3. If you are using HAStoragePlus for runtime files, unmount the shared disk.

To Configure HA on Node n Using a Local Disk for Configuration Files and Binaries Before You Begin

Ensure that you have completed HA configuration on Node 1 as described in the previous procedure (To Configure HA on Node 1 Using a Local Disk for Configuration Files and Binaries).

Have your answers for the checklists in Table 1-1 and Table 4-2 readily available.

1. Install products and packages using the Java Enterprise System installer.
   Choose the same path you used when you installed Instant Messaging on node 1 for each subsequent node in the cluster. See Selecting the Installation Directory (im-svr-base) for specific instructions.
   See Table 4-3 for a list of required products and packages for HA. Refer to the http://docs.sun.com/doc/819-7560 for specific instructions.
2. Run the configure utility.
   See [Chapter 1, Configuring Instant Messaging After Installation] for instructions.
3. When prompted for the Instant Messaging Server Runtime Files Directory, enter the same value that you provided for Node 1.
4. When prompted for the Instant Messaging host name, enter the same logical host you provided for Node 1.
   Choose to accept the logical host even if the configure utility cannot connect to the specified host. The logical host resource may be offline at the time you run the configure utility.
5. When prompted for the user and group, enter the same value that you provided for Node 1.
6. Do not choose to start Instant Messaging after configuration or on system startup.
   In an HA configuration, the Instant Messaging service also requires the logical host to be online for Instant Messaging to work properly.

To Configure HA on Node 1 Using a Shared Disk for Configuration Files and Binaries Before You Begin

Fill out the checklists in Table 1-1 and Table 4-2 and have your answers readily available.

You must use a cluster file system if you are using a shared disk for configuration files and binaries, not HAStoragePlus.

1. Install products and packages in a directory in the cluster file system using the Java Enterprise System installer.
   When you install Instant Messaging, you must specify a directory other than the default directory. See Selecting the Installation Directory (im-svr-base) for specific instructions.
   See Table 4-3 for a list of required products and packages for HA. Refer to thehttp://docs.sun.com/doc/819-7560 for specific instructions.
2. Create a soft link from /etc/opt/SUNWiim that points to /global/im/etc/opt/SUNWiim.
3. Run the configure utility from the global directory where you installed Instant Messaging (/global/im/im-svr-base/configure).
   See [Chapter 1, Configuring Instant Messaging After Installation] for instructions.
4. When prompted for the Instant Messaging Server Runtime Files Directory, enter the value for /global/im/im-runtime-base.
5. When prompted for the Instant Messaging host name, enter the logical host.
   Choose to accept the logical host even if the configure utility cannot connect to the specified host. The logical host resource may be offline at the time you run the configure utility.
6. Do not choose to start Instant Messaging after configuration or on system startup.
   In an HA configuration, the Instant Messaging service also requires the logical host to be online for Instant Messaging to work properly.

To Configure HA on Node n Using a Shared Disk for Configuration Files and Binaries Before You Begin

Ensure that you have completed HA configuration on Node 1 as described in the previous procedure (To Configure HA on Node 1 Using a Shared Disk for Configuration Files and Binaries).

Have your answers for the checklists in Table 1-1 and Table 4-2 readily available.

1. Create a soft link from /etc/opt/SUNWiim that points to /global/im/etc/opt/SUNWiim.
2. Create a soft link for the resource type registration (RTR) file:

   ln -s /global/im/im-svr-base/cluster/SUNW.iim  \
   /usr/cluster/lib/rgm/rtreg/SUNW.iim
   

Configuring the Logical Host

Before starting Instant Messaging, you need to create a resource group, add the logical host, and bring the resource group online.

To Configure the Resource Group With the Logical Host

1. Create an Instant Messaging failover resource group named im-resource-group:

   # scrgadm -a -g im-resource-group -h im-node-2,im-node-1
   

2. Add the logical host name im-logical-host to the resource group.
   Instant Messaging will listen on this host name.

   # scrgadm -a -L -g im-resource-group -l im-logical-host
   

3. Bring the resource group online:

   # scswitch -Z -g im-resource-group
   

Registering and Activating the Storage Resource

Before you can bring the Instant Messaging data service online, you need to register and activate the storage resource as described in this section.

To Register and Enable the Storage Resource

1. Register the storage resource.
   If you are using HAStoragePlus with a global file system (GFS), set the mount point as the value for the FileSystemMountPoints property. For example:

   # scrgadm -a -j im-resource-group-store -g im-resource-group -t SUNW.HAStorage   \
   -x FileSystemMountPoints=/global/im -x AffinityOn=True
   

   
   Otherwise, specify the mount point as the value for the ServicePaths property. For example:

   # scrgadm -a -j im-resource-group-store -g im-resource-group -t SUNW.HAStorage   \
   -x ServicePaths=/global/im -x AffinityOn=True
   

2. Enable the storage resource:

   # scswitch -e -j im-resource-group-store
   

Registering the Resource Type and Creating a Resource

Before you start the HA Instant Messaging server or multiplexor, you need to register the resource type SUNWiimsc with Sun Cluster and create a resource.

To Register the Resource Type and Create a Resource

1. Register the resource type.

   # scrgadm -a -t SUNW.iim
   

2. Create the resource.
   Enter the following command on a single line:

   # scrgadm -a -j im-resource -g im-resource-group -t SUNW.iim -x Confdir_list=/global/im/im-resource-group -y Resource_dependencies=im-resource-group-store
   

3. Enable the resource:

   # scswitch -e -j im-resource
   

4. Start Instant Messaging components.

Verifying the Instant Messaging HA Configuration

After you start Instant Messaging, you need to verify the HA configuration as described in this section.

To Verify the HA Configuration for Instant Messaging

1. Check that all required processes are running.
2. Conduct a switchover of the service to the backup node to ensure the high availability.
   For example, if the service is running on im-node-1, issue the following command to switch the service to im-node-2.

   # scswitch -z -g im-resource-group -h im-node-2
   

3. Check that all required processes are started on im-node-2.

Troubleshooting the Instant Messaging HA Configuration

To help with troubleshooting, error messages are written to the error log. The logs are controlled by the syslog facility. For information about using the logging facility, refer to the HA Related Documentation and to the man page for syslog.conf.

Top

Stopping, Starting, and Restarting the Instant Messaging HA Service

To start and stop the Instant Messaging HA service, use the Sun Cluster scswitch command.

For more information about the Sun Cluster scswitch command, refer to the Sun Cluster Reference Manual for Solaris OS.

To Start the Instant Messaging HA Service

1. Type the following at the command line:

   # scswitch -e -j im-resource
   

To Stop the Instant Messaging HA Service

1. Type the following at the command line:

   # scswitch -n -j im-resource
   

To Restart the Instant Messaging HA Service

1. Type the following at the command line:

   # scswitch -R -j im-resource
   

Top

Stopping, Starting, and Restarting Instant Messaging Components in a Deployment with Sun Cluster

The imadmin command checks to ensure it is not running on a cluster node before attempting to stop, start, or restart an Instant Messaging component. If imadmin determines that it is running on a cluster node, it returns an error instead of performing the command. Use the Sun Cluster administrative utilities to stop, start, and restart Instant Messaging components in a deployment with Sun Cluster.

Managing the HA RTR File for Instant Messaging

The resource type registration (RTR) file is an ASCII text file that describes a highly-available resource type that runs under the control of the Resource Group Manager (RGM). The RTR file is used as an input file by the scrgadm command to register the resource type into the cluster configuration. The Instant Messaging RTR file, SUNW.iim, is created when you install the SUNWiimsc package during HA configuration.

This section provides information about managing this file in the following sections:

Instant Messaging RTR File Parameters

The following table lists the extension properties in the Instant Messaging RTR file (SUNW.iim) that are specific to Instant Messaging.

Table 4-4 SUNW.iim Extension Properties

Customizing the RTR File for Instant Messaging

You can modify the values for several of the extension properties in the Instant Messaging RTR file (SUNW.iim) to configure your HA environment. Extension properties are properties that are specific to the resource type. These properties are inherited by every resource of the same type. Instant Messaging extension properties are described in Table 4-4.

See the documentation for rt_reg and property_attributes in the http://docs.sun.com/doc/819-3055 for more information on the contents of resource type registration files and instructions on customizing values for extension properties.

Choosing a High Availability Model for Your Instant Messaging Deployment

This section lists the high availability models, and describes the procedure to install and configure the asymmetric and symmetric models for deployment. This section contains the following topics:

The following table summarizes the advantages and disadvantages of each high availability model. Use this information to decide the appropriate model for your deployment.

High-Level Task List for an Asymmetric HA Deployment

The following is a list of the tasks necessary to install and configure Instant Messaging for asymmetric high availability:

1. Prepare the nodes.
   1. Install the Solaris operating system on all the nodes of the cluster.
   2. Install Sun Cluster software on all the nodes of the cluster.
   3. Install the Instant Messaging HA Agents package, SUNWiimsc, on all the nodes of the cluster by using the Communication Suite 6 Update 1 installer.
   4. Create a file system on the shared disk.
   5. Install Instant Messaging on all the nodes of the cluster by using the Communications Suite 6 Update 1 installer.
   6. Create a symbolic link from the Instant Messaging /etc/opt/SUNWiim directory to the shared disk IM_RUNTIME_DIR directory on all the nodes of the cluster.
2. Configuring the first or the primary node.
   1. Using the Sun Cluster command-line interface, set up HA on the primary node.
   2. Run the Instant Messaging configure utility on the primary node.
   3. Using the Sun Cluster command-line interface, create and enable a resource group for Instant Messaging.

For step-by-step instructions, see Installing and Configuring in an Asymmetric HA Environment.

High-Level Task List for a Symmetric HA Deployment

The following is a list of the tasks necessary to install and configure Instant Messaging for Symmetric High Availability:

1. Prepare the nodes.
   1. Install the Solaris operating system software on all the nodes of the cluster.
   2. Install the Sun Cluster software on all the nodes of the cluster.
   3. Create four file systems. You can create a cluster file systems or global file systems or failover file systems or local file systems.
   4. Create the necessary directories.
   5. Install the Instant Messaging HA Agents package, SUNWiimsc, on all nodes of the cluster by using the Communications Suit 6 installer.
2. Install and configure the first instance of Instant Messaging HA.
   1. Using the Communications Suite 6 installer, install Instant Messaging on the first node of the cluster.
   2. Using the Sun Cluster command-line interface, configure HA on the first node.
   3. Create a symbolic link from the Instant Messaging /etc/opt/SUNWiim directory to the shared disk IM_RUNTIME_DIR directory on the first node.
   4. Run the Instant Messaging configure utility on the first node.
   5. Using the Sun Cluster command-line interface, create and enable a resource group for Instant Messaging on the first node.
   6. Using the Sun Cluster command-line interface to test the successful creation of the resource group, perform a failover to the second node.
3. Install and configure the second instance of Instant Messaging HA.
   1. Using the Communications Suite 6 installer, install Instant Messaging on the second node of the cluster.
   2. Using the Sun Cluster command-line interface, configure HA on the second node.
   3. Create a symbolic link from the Instant Messaging /etc/opt/SUNWiim directory to the shared disk IM_RUNTIME_DIR directory on the secondary node.
   4. Run the Instant Messaging configure utility on the second node.
   5. Using the Sun Cluster command-line interface, create and enable a resource group for Instant Messaging on the second node.
   6. Using the Sun Cluster command-line interface to test the successful creation of the resource group, perform a failover to the first node.

For step-by-step instructions, see Installing and Configuring in a Symmetric HA Environment.

Installing and Configuring in an Asymmetric HA Environment

This section contains instructions for configuring an asymmetric high availability Instant Messaging cluster. This sections contains the following topics:

• Creating the File Systems for Your HA Deployment
• Creating the Instant Messaging Directory on All Shared Disks of the Cluster in Your HA Deployment
• Installing and Configuring HA for Instant Messaging 8

Creating File Systems for HA Deployment

Create a file system on the shared disk. The /etc/vfstab directory should be identical on all the nodes of the cluster.

For the cluster file system (CFS), the directory should be similar to the following example.

## Cluster File System/Global File System ##
/dev/md/penguin/dsk/d400 /dev/md/penguin/rdsk/d400 /global/im ufs 2 yes global,logging

For the failover file system (FFS), the directory should be similar to the following example.

## Fail Over File System/Local File System ##
/dev/md/penguin/dsk/d400 /dev/md/penguin/rdsk/d400 /local/im ufs 2 no logging

Note The fields in these commands are separated by tabs and not spaces.

Creating the Instant Messaging Directory on all the Shared Disks of the Cluster in the HA Deployment

For all the nodes of the cluster, create a directory, IM_RUNTIME_DIR, to store the configuration details and data. For example, to create an Instant Messaging directory on a shared disk, type either one of the following:
mkdir -p /local/im
or
mkdir -p /global/im

Installing and Configuring HA for Instant Messaging 8 Software

This section contains instructions for the tasks involved in installing and configuring HA for Instant Messaging. Perform the following tasks to complete the configuration:

Preparing Each Node of the Cluster

For each node in the cluster, create the Instant Messaging runtime user and group under to run the components. The user ID (UID) and group ID (GID) numbers must be the same on all the nodes in the cluster.

• Runtime User ID: User name using which the Instant Messaging server runs. The default value is inetuser.
• Runtime Group ID: Group using which the Instant Messaging server runs. The default value is inetgroup.
  Although the configure utility creates the IDs, you can create the IDs before you invoke the configure utility as part of the preparation of each node. Create the runtime user and group ID on a node where you will not invoke the configure utility, which is usually secondary node.

Make sure that the username, group name and the corresponding user ID and group ID are same in the following files on all nodes:

• inetuser or the name that you select in the /etc/passwd directory on all the nodes in the cluster
• inetgroup or the name that you select in the /etc/group directory on all the nodes in the cluster

Refer to your operating system documentation for detailed information about users and groups.

Installing Instant Messaging

Selecting the Installation Directory IM_SVR_BASE

For Instant Messaging and Instant Messaging Sun Cluster agent IM_SCHA, the Communications Suite 6 installer uses the /opt/sun/comms directory on the Solaris operating system as the default installation directory. The value of the IM_SVR_BASE variable is /opt/sun/comms/im.

However, if you are using a shared disk for binaries, you must specify a cluster file system (CFS) or a failover file system (FFS) installation directory. For example, if /global/im/ is the installation directory, then the value of IM_SVR_BASE is /global/im/im.

If you are using a local disk, you should install the Instant Messaging in the same directory on each machine in the node.

Note Configuration files and runtime files reside on a CFS or on a highly-available FFS. Binaries are installed on local file systems on each node at the same location. Enables rolling upgrade of the Instant Messaging software. Binaries, configuration files and runtime files either reside on a CFS or on a highly-available FFS. The Instant Messaging installation is required only on one node as the binaries are shared across all the nodes. Instant Messaging upgrade needs a server down time.

Installing Instant Messaging Products and Packages

Install products and packages by using the Communications Suite 6 Update 1 installer program. For more information about the installer, refer to the Sun Java Communications Suite 6 Update 1 Installation Guide. The following table lists the products or packages required for a multiple node cluster configuration.

Instant Messaging HA Agent Installation

To install the Instant Messaging Sun Cluster HA agent, perform the following steps:

1. Type the Communications Suite installer command in the global zone.
   # commpkg install

   Note In case of Solaris 10 zones, run the above command from global and non-global zones.

2. Select the Instant Messaging Sun Cluster HA Agent software when prompted.
3. Type the Sun Cluster HA Agent preconfiguration command.
   # IM_SCHA_BASE/bin/init-config

   Note In case of Solaris 10 zones, run the above command only from the global zone.

Setting Up the Primary Node

Use the Sun Cluster command line interface to set up HA on the first node.

1. Register the Instant Messaging and HAStoragePlus resource.

   ./scrgadm -a -t SUNW.HAStoragePlus
   ./scrgadm -a -t SUNW.iim
   

2. Create a failover Instant Messaging resource group. For example, for a two node asymmetric cluster setup, the following command creates the Instant messaging resource group IM-RG with the primary node as NODE1 and the secondary, or failover, node as NODE2.
   ./scrgadm -a -g IM-RG -h IM_NODE1,IM_NODE2
3. Create a logical hostname resource in the Instant Messaging resource group and change the resource group state to online. For example, the following instructions create the logical hostname resource LOG_HOST_RS and bring the resource group IM-RG to online state.

   ./scrgadm -a -L -g IM-RG -l LOG_HOST_RS
   ./scrgadm -c -j LOG_HOST_RS -y    \
         R_description="LogicalHostname resource for LOG_HOST_RS"
   ./scswitch -Z -g IM-RG
   

4. Create and enable the HAStoragePlus resource. For example, the following commands create and enable the HAStoragePlus resource IM_HASP_RS.

   scrgadm -a -j IM_HASP_RS -g IM-RG -t
        SUNW.HAStoragePlus:4 -x FilesystemMountPoints=/IM_RUNTIME_DIR
   scrgadm -c -j IM_HASP_RS -y
        R_description="Failover data service resource for SUNW.HAStoragePlus:4"
   scswitch -e -j IM_HASP_RS
   

5. Create a symbolic link from the Instant Messaging /etc/opt/SUNWiim directory to the shared disk IM_RUNTIME_DIR directory on all the nodes of the cluster.

For example, type the following commands on all the nodes of the cluster:

# pwd
/etc/opt/

# ln -s /IM_RUNTIME_DIR SUNWiim

Invoking the configure Utility on the Primary Node

1. Invoke the configure utility. For example, from the /IM_SVR_BASE directory type the following command:

   # pwd
        /IM_SVR_BASE
   
   # ./configure
   

   For further information about the configure utility, see Configuring Instant Messaging After Installation.

2. When prompted for the Instant Messaging Server runtime files directory IM_RUNTIME_DIR, type either of the following commands:
   a. If you are using failover file system for the runtime files, type /local/im/.
   b. If you are using a cluster file system for the runtime files, type /global/im/.
3. If prompted for the Instant Messaging host name, type the logical host. Choose to accept the logical host even if the configure utility is unable to connect to the specified host. The logical host resource might be offline at the time when you invoke the configure utility.
4. Do not start Instant Messaging after configuration or on system startup.
5. Change the value of the iim_wd.period parameter to "60" and the iim_wd.maxRetries parameter to "2" in the {{ /IM_RUNTIME_CONFIG/iim.conf}} file.
6. Create and enable the Instant Messaging resource.
   In this example, the resource group name is IM_SVR_RS. Provide the logical host resource name and the HAStoragePlus resource name. For example,

   ./scrgadm -a -j IM_SVR_RS -g IM-RG
        -t SUNW.iim -x Server_root=/IM_SVR_BASE
        -x Confdir_list=/IM_RUNTIME_CONFIG 	(ex: /local/im/default/config )
        -y Resource_dependencies=IM_HASP_RS,LOG_HOST_RS
   
   ./scrgadm -e -j IM_SVR_RS
   

7. Test the successful creation of the Instant messaging resource group by performing a failover.
   ./ scswitch -z -g IM-RG -h IM_NODE2

   Note You do not need to configure the second node as the configuration is shared between all the nodes by soft links pointing to the shared location.

Installing and Configuring in a Symmetric HA Environment

This section contains instructions for configuring a symmetric high availability Instant Messaging system. To configure a symmetric high availability Instant Messaging system, perform the steps described in the following sections:

• Initial Tasks
• Installing and Configuring the First Instance of Instant Messaging
• Installing and Configuring the Second Instance of Instant Messaging

Initial Tasks
You must complete the following preparatory tasks before installing Instant Messaging on the nodes. The preparatory tasks are:
I. Creating File Systems
II. Installing the Instant Messaging HA Package
III. Preparing Each Node of the Cluster

I. Creating File Systems
Instant Messaging binaries, configuration files, and runtime files reside on the CFS or on the highly available FFS. For each Instant Messaging instance, installation is needed on only one node as the binaries are shared across all the nodes.

To create file systems, perform the following steps:

1. Create four file systems by using CFS or FFS.
   To create a system by using CFS, for example, the contents of the /etc/vfstab file should appear as follows.

   # Cluster File System/Global File System ##
   /dev/md/penguin/dsk/d500  /dev/md/penguin/rdsk/d500
       /INSTALL-ROOTIM1  ufs  2  yes  logging,global
   /dev/md/penguin/dsk/d400  /dev/md/penguin/rdsk/d400
       /share-disk-dirIM1  ufs  2  yes  logging,global
   /dev/md/polarbear/dsk/d200  /dev/md/polarbear/rdsk/d200
       /INSTALL-ROOTIM2  ufs  2  yes  logging,global
   /dev/md/polarbear/dsk/d300  /dev/md/polarbear/rdsk/d300
       /share-disk-dirIM2  ufs  2  yes logging,global
   

   Note The fields must be separated by tabs.

   To create a system by using FFS, for example, the contents of the /etc/vfstab file should appear as follows.

   # Failover File System/Local File System ##
   /dev/md/penguin/dsk/d500  /dev/md/penguin/rdsk/d500
       /INSTALL-ROOTIM1  ufs  2  yes  logging
   /dev/md/penguin/dsk/d400  /dev/md/penguin/rdsk/d400
       /share-disk-dirIM1  ufs  2  yes  logging
   /dev/md/polarbear/dsk/d200  /dev/md/polarbear/rdsk/d200
       /INSTALL-ROOTIM2  ufs  2  yes  logging
   /dev/md/polarbear/dsk/d300  /dev/md/polarbear/rdsk/d300
       /share-disk-dirIM2  ufs  2  yes logging
   

   Note The fields must be separated by tabs.

   
   

2. Create the following mandatory directories on all the nodes of the cluster.

   # mkdir -p /INSTALL-ROOTIM1 share-disk-dirIM1
        INSTALL-ROOTIM2 share-disk-dirIM2
   

II. Installing the Instant Messaging HA Package
Install the Instant Messaging Sun Cluster HA package in two nodes. You can use the Communication Suite 6 Update 1 installer to install the HA package.
To install the Instant Messaging Sun Cluster HA agent, perform the following steps:

1. 1. Run the Communications Suite 6 installation command.
      # commpkg install

      Note In case of Solaris 10 zone, run the above command from the global and non-global zones.

2. When prompted, select the Instant Messaging Sun Cluster HA Agent software.
3. Type the Sun Cluster HA Agent pre-configuration command.
   # <IM_SCHA_BASE>/bin/init-config

   Note In case of Solaris 10 zone, run the above command only from the global zone.

III. Preparing Each Node of the Cluster
For each node in the cluster, create the Instant Messaging runtime user and group under which the components will run. The user ID (UID) and group ID (GID) numbers must be the same on all nodes in the cluster.

• Runtime User ID: User name using which the Instant Messaging server runs. The default value is inetuser.
• Runtime Group ID: Group using which the Instant Messaging server runs. The default value is inetgroup.
  Although the configure utility creates these IDs, you can create the IDs before you invoke the configure utility as part of the preparation of each node. Create the runtime user and group ID on a node where you might not invoke the configure utility, which is usually secondary node.

Make sure that the username, group name and the corresponding user ID and group ID are same in the following files on all nodes:

• inetuser or the name that you select in the /etc/passwd directory on all the nodes in the cluster
• inetgroup or the name that you select in the /etc/group directory on all the nodes in the cluster

Refer to your operating system documentation for detailed information about users and groups.

Installing and Configuring the First Instance of Instant Messaging

To install the first instance of Instant Messaging, perform the following steps:

1. Verify whether the files are mounted.
   On the primary node Node1, type the following command:
   df -k
   The following message shows a sample output:

   /dev/md/penguin/dsk/d500     35020572
        34738 34635629   1%   /INSTALL-ROOTIM1
   /dev/md/penguin/dsk/d400     35020572
        34738 34635629   1%   /share-disk-dirIM1
   

2. Using the Communications Suite 6 installer, install Instant Messaging on the primary node.
   1. Type the Communications Suite installer command.
      # commpkg install

      Note In case of Solaris 10 zones, refer to the Sun Java Communications Suite 6 Installation Guide.

   2. At the Specify Installation Directories prompt, type the installation root INSTALL-ROOTIM1.
3. Create a symbolic link from the Instant Messaging the /etc/opt/SUNWiim directory to the shared disk IM_RUNTIME_DIR directory on all the nodes of the cluster. For example, type the following commands on a cluster node:

   # pwd
   /etc/opt/
   
   # ln -s /share-disk-dirIM1 SUNWiim
   

To configure Sun Cluster on the first node by using the Sun Cluster command-line interface, perform the following steps:

1. Register the following resource types.

   ./scrgadm -a -t SUNW.HAStoragePlus
   ./scrgadm -a -t SUNW.iim
   

2. Create a failover resource group.
   In the following example, the resource group is IM-RG1, IM_NODE1 is the primary node and IM_NODE2 is the failover node.
   ./scrgadm -a -g IM-RG1 -h IM_NODE1,IM_NODE2
3. Create a logical hostname resource for the node.
   Add the logical host name LOG_HOST_RS to the resource group. Instant Messaging listens on this hostname. The following example uses LOG-HOST-IM-RS1. Replace this value with the actual hostname.

   ./scrgadm -a -L -g IM-RG1 -l LOG-HOST-IM-RS1
   ./scrgadm -c -j LOG-HOST-IM-RS1 -y R_description=
        "LogicalHostname resource for LOG-HOST-IM-RS1"
   

4. Bring the resource group online.
   scswitch -Z -g IM-RG1
5. Create a HAStoragePlus resource and add it to the failover resource group.
   In this example, the resource is called IM_HASP_RS1. Replace the resource with your own resource name.

   Note The example is split for display purpose in this document.

   ./scrgadm -a -j IM-HASP-RS1 -g IM-RG1 -t
        SUNW.HAStoragePlus:4 -x FilesystemMountPoints=/INSTALL-ROOTIM1,
        /share-disk-dirIM1
   ./scrgadm -c -j IM-HASP-RS1 -y R_description="Failover data
        service resource for SUNW.HAStoragePlus:4"
   

6. Enable the HAStoragePlus resource.
   ./scswitch -e -j IM-HASP-RS1

To configure the first instance of Instant Messaging, perform the following steps:

1. Run the configure utility on the primary node.

   # cd /INSTALL-ROOTIM1/im
   # ./configure
   

   For more information about the configure utility, see configure Utility.

2. When prompted for the Instant Messaging Server Runtime Files Directory, type /share-disk-dirIM1 if you are using HAStoragePlus for the runtime files.
3. When prompted for the Instant Messaging host name, type the logical host.
   Choose to accept the logical host even if the configure utility cannot connect to the specified host. The logical host resource might be offline at the time when you invoke the configure utility.
4. Do not start Instant Messaging after configuration or on system startup.
5. Change the value of the iim_wd.period parameter to "60" and the iim_wd.maxRetries parameter to "2" in the {{ /IM_RUNTIME_CONFIG/iim.conf}} file.
6. Create and enable the Instant Messaging resource.
   In this example, the resource group name is IM_SVR_RS1.Provide the logical host resource name and the HAStoragePlus resource name.

   ./scrgadm -a -j IM_SVR_RS1 -g IM-RG1
        -t SUNW.iim -x Server_root=/INSTALL-ROOTIM1/im
        -x Confdir_list=/share-disk-dirIM1/default/config
        -y Resource_dependencies=IM-HASP-RS1,LOG-HOST-IM-RS1
   
   ./scrgadm -e -j IM_SVR_RS1
   

7. Test the successful creation of the Instant Messaging resource group by performing a failover.
   ./ scswitch -z -g IM-RG1 -h IM_NODE2

   Note You do not have to configure the second node as configuration is shared between all the nodes by soft links pointing to shared location.

   Installing and Configuring the Second Instance of Instant Messaging

To install the second instance of Instant Messaging, perform the following steps:

1. Verify whether the files are mounted. On the primary node IM_NODE2, type:
   df -k
   The following output is displayed:

   /dev/md/polarbear/dsk/d300   35020572
        34738 34635629   1%   /share-disk-dirIM2
   /dev/md/polarbear/dsk/d200   35020572
        34738 34635629   1%   /INSTALL-ROOTIM2
   

2. Using the Communications Suite 6 installer, install Instant Messaging on the primary node.
   1. Type the Communications Suite installation command.
      # commpkg install

      Note In case of Solaris 10 zones, refer to the Sun Java Communications Suite 6 Installation Guide.

   2. At the Specify Installation Directories prompt, specify the installation root INSTALL-ROOTIM2.
3. Create a symbolic link from the Instant Messaging /etc/opt/SUNWiim directory to the shared disk IM_RUNTIME_DIR directory on this cluster node.
   For example, type the following commands on all the nodes of the cluster:

   # pwd
   /etc/opt/
   
   # ln -s /share-disk-dirIM2 SUNWiim
   

Configuring Sun Cluster on the Second Node

To configure Sun Cluster on the second node by using the Sun Cluster command-line interface, perform the following steps:

1. Create a failover resource group.
   In the following example, the resource group is IM-RG2, IM_NODE2 is the primary node and IM_NODE1 is the failover node.
   ./scrgadm -a -g IM-RG2 -h IM_NODE2,IM_NODE1
2. Create a logical hostname resource for this node.
   Add the logical host name LOG_HOST_RS to the resource group. Instant Messaging will listen on this host name. The following example uses LOG-HOST-IM-RS2 in the place where you will substitute in the actual hostname.

   ./scrgadm -a -L -g IM-RG2 -l LOG-HOST-IM-RS2
   ./scrgadm -c -j LOG-HOST-IM-RS2 -y R_description=
        "LogicalHostname resource for LOG-HOST-IM-RS2"
   

3. Bring the resource group online.
   scswitch -Z -g IM-RG2
4. Create a HAStoragePlus resource and add it to the failover resource group.
   In this example, the resource is called IM-HASP-RS2. Replace it by your own resource name. Note that the lines are divided and show as two lines in the example for display purposes in this document.

   ./scrgadm -a -j IM-HASP-RS2 -g IM-RG2 -t
        SUNW.HAStoragePlus:4 -x FilesystemMountPoints=/INSTALL-ROOTIM2,
        /share-disk-dirIM2
   ./scrgadm -c -j IM-HASP-RS2 -y R_description="Failover data
        service resource for SUNW.HAStoragePlus:4"
   

5. Enable the HAStoragePlus resource.
   ./scswitch -e -j IM-HASP-RS2

To configure the second instance of Instant Messaging, perform the following steps:

1. Run the configure utility on the primary node.

   # cd /INSTALL-ROOTIM2/im
   
   # ./configure
   

   For more information about the configure utility, see configure Utility.

2. When prompted for the Instant Messaging Server Runtime Files Directory, type one of the following:
   If you are using an HAStoragePlus for the runtime files, type /share-disk-dirIM2
3. When prompted for the Instant Messaging host name, type the logical host.
   For example, accept the logical host even if the configure utility cannot connect to the specified host. The logical host resource might be offline when you invoke the configure utility.
4. Do not start Instant Messaging after configuration or on system startup.
   In an HA configuration, the Instant Messaging service requires the logical host to be online for Instant Messaging to work correctly.
5. Change the value of the iim_wd.period parameter to "60" and the iim_wd.maxRetries parameter to "2" in the {{ /IM_RUNTIME_CONFIG/iim.conf}} file.
6. Create the Instant Messaging resource and enable the resource.
   In this example, the resource group name is IM_SVR_RS2.Provide the logical host resource name, the HAStoragePlus resource name, and the port number. By default, Instant Messaging uses ports 5269,5222 and 45222. If the first instance uses these port numbers, use different port numbers for the second instance.

   ./scrgadm -a -j IM_SVR_RS2 -g IM-RG2
        -t SUNW.iim -x Server_root=/INSTALL-ROOTIM2/im
        -x Confdir_list=/share-disk-dirIM2/default/config
        -y Resource_dependencies=IM-HASP-RS2,LOG-HOST-IM-RS2
        -x port_list="5270/tcp","5223/tcp","45223/tcp"
   

7. Test the successful creation of the Instant messaging resource group by performing a failover.
   ./ scswitch -z -g IM-RG2 -h IM_NODE1

   Note You do not have to configure the second node as configuration is shared between all the nodes by soft links pointing to shared location.

Starting and Stopping the Instant Messaging HA Service

To start and stop the Instant Messaging HA service, use the Sun Cluster scswitch command.

Caution Do not use the imadmin start, imadmin stop, or imadmin refresh commands in a HA environment with Sun Cluster. Instead, use the Sun Cluster administrative utilities. For more information about the Sun Cluster scswitch command, refer to the Sun Cluster Reference Manual for Solaris OS.

To start the Instant Messaging HA service, type the following command:
# scswitch -e -j IM_SVR_RS

To stop the Instant Messaging HA service, type the following command:
# scswitch -n -j IM_SVR_RS

To restart the Instant Messaging HA Service, type the following command:
# scswitch -R -j IM_SVR_RS

Troubleshooting the Instant Messaging HA Configuration

To help troubleshooting error messages are stored in the error log. The logs are controlled by the syslog facility. For information about using the logging facility, see the HA Related Documentation and the syslog.conf man page.

Top

Removing HA for Instant Messaging

In order to remove Instant Messaging from an HA environment, you need to remove the Instant Messaging cluster agent SUNWiimsc as described in this section.

To Remove HA for Instant Messaging Before You Begin

When you remove the SUNWiimsc package as described in this procedure, any customizations you made to the RTR file SUNW.iim are lost. If you want to restore them at a later time, you need to create a backup copy of SUNW.iim before removing the SUNWiimsc package.

1. Bring down the Instant Messaging data service:

   scswitch -F -g im-resource-group
   

2. Disable all resources in the Instant Messaging resource group (im-resource-group):

   # scswitch -n -j im-resource
   # scswitch -n -j im-logical-host
   # scswitch -n -j im-resource-group-store
   

3. Remove the resources from the Instant Messaging resource group:

   # scrgadm -r -j im-resource
   # scrgadm -r -j im-logical-host
   # scrgadm -r -j im-resource-group-store
   

4. Remove the Instant Messaging resource group:

   # scrgadm -r -g im-resource-group
   

5. Remove the Instant Messaging resource type:

   # scrgadm -r -t SUNW.iim
   

6. Remove the SUNWiimsc package using the Java Enterprise System installer or manually as follows:

   pkgrm SUNWiimsc
   

   When you remove the package, any customizations you made to the RTR file are lost.

7. If you are using a shared directory for configuration files and binaries, remove any soft links created during HA configuration.
   On Node 1:

   rm /etc/opt/SUNWiim
   

   On all other nodes:

   rm /usr/cluster/lib/rgm/rtreg/SUNW.iim
   

Top

HA Related Documentation

• Sun Java Enterprise System 2005Q4 Technical Overview.
• http://docs.sun.com/doc/819-7560 describes the Communications Suite installer (and uninstaller) and the supported installation scenarios.
• http://docs.sun.com/doc/819-4893 provide current information about the Sun Java Enterprise System product.
• http://docs.sun.com/doc/819-2969 provides a general background about Sun Cluster software, data services, and terminology resource types, resources, and resource groups.
• http://docs.sun.com/doc/819-2974 provides general information on planning and administration of data services.
• http://docs.sun.com/doc/819-2971 provides the software procedures for administering a Sun Cluster configuration.
• http://docs.sun.com/doc/819-3055 describes the commands and utilities available with the Sun Cluster software, including commands found only in the SUNWscman and SUNWccon packages.
• http://docs.sun.com/doc/819-4439 provides further information about how HA is implemented in Instant Messaging.