Previous      Contents      Index      Next
Sun Java System Application Server 7 2004Q2 Update 1 Standard and Enterprise Edition Installation Guide

Chapter 2
Preparing for HADB Setup

After the high-availability components are installed on the servers that will be part of a cluster, you are ready to set up high availability.

The following topics are addressed here:

Setting up HADB on Windows
Configuring Shared Memory and Semaphores
Setting Up Host Communication
Setting Up the User Environment
Setting Up Administration for Non-Root
Using clsetup
Time Synchronization

After you have done the tasks here, proceed to the Sun Java System Application Server Administration Guide for comprehensive instructions on configuring and managing the cluster, the load balancer plug-in, and the high-availability database (HADB).

Information on high-availability topologies is available in the Sun Java System Application Server System Deployment Guide.

---

Setting up HADB on Windows

The version of HADB available on the Windows platform is 4.4.x compared to the version on UNIX platforms, which is 4.3.x. As such, there are a few changes from the UNIX version for configuring and administering HADB on Windows. These changes are called out at appropriate places in this chapter.

To setup an Application Server cluster along with an HADB database, you can use the clsetup utility on windows platforms, as described in Using clsetup. The examples in this section are UNIX-specific. Ensure that you make the appropriate changes for Windows platforms.

For details on setting up and running HADB on Windows platform, see Chapter 21, Administering High Availability on Windows,” in Sun Java System Application Server 7 2004Q2 Update 1 Administration Guide.

The major differences between the two HADB versions are:

New HADB management system. As a result, there are a few new commands added to hadbm and a few old ones have been deprecated.
RSH/SSH configuration is not required on Windows platforms.
New adminpassword option added to hadbm command. This administration password is different from the dbpassword.
A few important limitations of the 4.3 version of HADB have been removed in the 4.4 version.
A management agent process (that serves management requests from the hadbm, should be running before an HADB instance can be created.

For more information on these and other changes in HADB 4.4.x, see Sun Java System Application Server 7 2004Q2 Update 1 Administration Guide.

Note	Windows might have to be reconfigured when HADB creates more than 60-80 SQL server processes. This may occur if you have configured too many JDBC connections in HA Store, or transiently after an application server has failed and then restarted. If you have not configured windows, you might get the following error message in a pop-up window: clu_sql_srv.exe: The application failed to initialize properly (0xc00000142). This message is also registered in the event log. In the HADB server log, you will see a warning message such as, Server time out waiting for sub-process, waited for 10 seconds. To avoid this problem, configure Windows as described here: 1.  Reduce the number of JDBC connections that can be created against the database, or 2.  Update the Windows registry according to the following procedure: http://support.microsoft.com/default.aspx?scid=kb;[LN];184802 (Cause 2).

---

Configuring Shared Memory and Semaphores

This sections contains instructions for configuring shared memory for the HADB host machines on UNIX platforms. You must configure the shared memory before working with the HADB.

Note	This configuration is not required on Windows platform.

Configuring Shared Memory on Solaris
Configuring Shared Memory on Linux

Configuring Shared Memory on Solaris

Log in as root.
Add the following to the /etc/system file for shared memory:

set shmsys:shminfo_shmmax=0x80000000
set shmsys:shminfo_shmseg=20

This example sets maximum shared memory shmmax to 2GB (hexadecimal 0x80000000) which is sufficient for most configurations.

The shmsys:shminfo_shmmax setting is calculated as 0x10000000 per 256 MB and should set to be identical to the memory size for the host. To determine your host’s memory, run this command:

prtconf | grep Memory

Then plug the value into the following formula:

((<host> MB / 256 MB) * 0x10000000)

Note	Note that the maximum value for shmsys:shminfo_shmmax is 0xffffffff.

For semaphores:

Your /etc/system file may already contain semmni, semmns, and semmnu entries. For example:

set semsys:seminfo_semmni=10
set semsys:seminfo_semmns=60
set semsys:seminfo_semmnu=30

If the entries are present, increment the values by adding 16, 128, and 1000 respectively, as follows:

set semsys:seminfo_semmni=26
set semsys:seminfo_semmns=188
set semsys:seminfo_semmnu=1030

If your /etc/system file does not contain the above mentioned entries, add the following entries at the end of the file:

set semsys:seminfo_semmni=16
set semsys:seminfo_semmns=128
set semsys:seminfo_semmnu=1000

This is sufficient to run up to 16 HADB nodes on the computer.

Reboot the computer for the shared memory settings to take effect.

Consult the HADB chapter in the Sun Java System Performance Tuning Guide if there will be more than 16 nodes.

Configuring Shared Memory on Linux

To increase the shared memory to 512 MB, run the following:

echo 536870912 > /proc/sys/kernel/shmmax
echo 536870912 > /proc/sys/kernel/shmall

shmmax is the maximum size of a single shared memory segment and shmall is the total shared memory to be made available.

For a standard HADB node that uses default values, this value is enough. If you want larger size, then you have to increase it.

The default shared memory limit for shmmax can be changed in the proc file system without having to reboot your machine. Additionally, you can use sysctl(8) to change it.
To make these changes permanent, add this line to /etc/sysctl.conf file. This file is used during the boot process.

echo kernel.shmmax=536870912 /etc/sysctl.conf

For an explanation of HADB nodes, see the section titled: Configuring the HADB in the Administering the High-Availability Database (Enterprise Edition) chapter of the Sun Java System Application Server Administration Guide. Additionally, consult the Sun Java System Application Server Performance Tuning Guide to learn about stress and performance testing.

---

Setting Up Host Communication

Note	RSH/SSH configuration is not required on Windows platform.

To implement remote access for HADB administration, all machines that will be running HADB servers and the HADB management client must be configured for Remote Shell (RSH) or Secured Shell (OpenSSH/SSH). This procedure is required on UNIX platforms only.

RSH is a simple remote shell command and does not have any security features. The SSH communication channel provides a level of security by encrypting the data that passes between the HADB nodes.

Note	For Solaris 9 & 10,the default installation of SSH is recommended. On Solaris 8, by default SSH is not installed. Follow the instructions in Installing SSH for Solaris 8 if SSH is not on your Solaris 8 system. If you want to use SSH, but it is not configured, you will not be able to use the hadbm command. Refer to SSH Requirements and Limitations to verify that SSH is recognized.

This section contains instructions for:

Setting Up RSH for HADB Administration
Setting Up SSH for HADB Administration

Setting Up RSH for HADB Administration

If you want to use RSH instead of SSH, you must explicitly specify RSH using the set managementProtocol option. Refer to Table 2-3 for guidelines on setting this parameter in the clresource.conf file.

SSH is the strongly recommended default for the hadbm create command because SSH is more secure than RSH.

To implement RSH:

Log in as root.
For Linux platform only, append the /etc/securetty file with the following:

rexec
rsh
rlogin
pts/0
pts/1

Additionally, under /etc/xinetd.d/ change disable=no in the rexec, rlogin, and rsh files.

Edit the /etc/hosts file to contain entries for all the selected HADB hosts, including the host name of the local host. Use localhost format. For example:

computer1.xbay.company.com
computer99.zmtn.company.com

Append this file to the /etc/hosts file of all selected installation hosts.
Create a .rhosts file in the $HOME directory of the HADB user.
Verify that permissions are set to Read Only for group and other.

Add the host name of each HADB host, including the name of your local host, followed by the name of your database user. For example, if the database user is Jon:

computer1.xbay.company.com Jon
computer99.zmtn.company.com Jon
mine456.red.mycompany.com       Jon

Append this file to the .rhosts file of each HADB host.
Check host communication for each host. For example:

rsh computer99.zmtn.company.com uname -a

The identity is returned from the other host.

Setting Up SSH for HADB Administration

SSH is strongly recommended for using the hadbm create command because SSH is more secure than RSH.

Note	From a security perspective, the DSA-based version 2 protocol is recommended instead of the RSA-based version 1 protocol. The version you select depends on the SSH client software in use at your site.

This section contains the following sections:

SSH Requirements and Limitations
Installing SSH for Solaris 8
Configuring SSH

SSH Requirements and Limitations

Note	SSH is installed by default on Solaris 9 systems, however, on Solaris 8, by default, SSH is not installed. To install SSH for Solaris 8 see Installing SSH for Solaris 8.

You may need to take action on any or all of the following requirements during your SSH setup:

Location of the SSH binaries—The high-availability management client expects to find the ssh and scp binaries in the following location on each HADB host:

/usr/bin

If the binaries are on your system but this location is not correct, you will need to make a symbolic link from /usr/bin to the correct location.
If you are on a Solaris 8 system, the SSH binaries are not installed by default and so may not be present. If this is the case, follow the instructions in "Installing SSH for Solaris 8," on page 45.

Support—The only tested support is for SunSSH and OpenSSH. If you are using another version of SSH, it is best to refer to the setup instructions in that product’s documentation to ensure that your SSH communications work correctly.
OpenSSH clients and daemons—If you are running in an environment with OpenSSH clients and daemons, you should name the key file as follows:

~/.ssh/authorized_keys2 or ~/.ssh/authorized_keys.

Running as root—If you are running the HADB admin clients as root, make sure that the sshd configuration (/etc/ssh/sshd_config) on all machines has the PermitRootLogin parameter set to yes.

Note	By default, Sun SSH does not permit root login; it is set to no. If the sshd configuration is changed, sshd must be restarted. Type the following to restart the service: /etc/init.d/sshd stop/start

No SSH protocol version 2 support—If your SSH clients and daemons do not support SSH protocol version 2, you will need to run ssh-keygen without options. The key file will then be named identity.pub instead of id_dsa.pub. This file must be appended to ~/.ssh/authorized_keys.
Mixed SSH environment—If you are operating in a mixed SSH environment, you will need to create both files ~/.ssh/authorized_keys2 and ~/.ssh/authorized_keys; the latter may contain both version 1 and version 2 keys.
Co-location—If the Sun Java System Application Server and the HADB are co-located on the same machine, you will need to create a known_hosts file under the .ssh directory by running one of the following commands:

ssh localhost

or

ssh hostname

Installing SSH for Solaris 8

The ssh and scp binaries are not installed by default on Solaris 8 systems. If the binaries are not on your Solaris 8 system, perform these steps:

Go to the following site:

http://www.sunfreeware.com/openssh8.html

On this site, you may receive a message similar to the following:

===PLEASE NOTE!!!............ make a note of some of the mirror sites so that if the servers are down, you can still download from a mirror site.

If you receive such a message, try one of the many mirror sites listed in the FTP/Mirror Sites link. For example:

http://sunfreeware.secsup.org/

On this site, follow the instructions in the Installation Steps to download and install all the necessary OpenSSH packages and patches.

You are now ready to configure SSH.

Configuring SSH

To set up SSH on a system where the ssh and scp binaries are already installed, perform the steps in one of the following sections:

SSH for Non-Mounted Home Directories
SSH for Mounted Home Directories

SSH for Non-Mounted Home Directories

To implement SSH in systems with home directories that are not mounted, perform these steps:

Verify that SSH requirements have been understood and met as specified in SSH Requirements and Limitations.
Log in to the host as the HADB user.
Generate your keys by running the following:

ssh-keygen -t dsa

For SSH1 and OpenSSH/1, you normally do not need to give any parameters to the ssh-keygen command.

For the next three prompts, accept the default options by pressing Enter.
Repeat steps 1, 2, and 3 for all machines in your cluster.

A file called identity.pub or id_dsa.pub (depends on whether you are using SSH version 1 or version 2) located in your ~/.ssh directory holds the public key. To connect to a machine without being asked for a password, the content of this file must be appended to a file called authorized_keys on all the machines.

To set up login identity, go to your user directory:

~/.ssh.

For SSH1, OpenSSH/1:

Copy the identity.pub file and name it authorized_keys.
For each of the other machines in the cluster, copy the content of the identity.pub file and append it to the local authorized_keys file.

OpenSSH/2:

Copy the id_dsa.pub file and name it authorized_keys2.
For each of the other machines in the cluster, copy the content of the id_dsa.pub file and append it to the local authorized_keys2 file.
Copy the authorized_keys file to the ~/.ssh directory on all the HADB machines.
Verify that the.ssh directory, HADB user’s home directory, and the .ssh/authorized_keys file do not have write permissions for group and other.

If needed, disable these group/other write permissions as follows:

chmod og-w ~/.ssh
chmod og-w ~/.ssh/authorized_keys
chmod og-w $HOME

Replace $HOME with the home directory of the HADB user. For example:

chmod og-w ~/johnsmith

Note	If the files under the ~/.ssh directory have even read permission given to group/other, you cannot set up an automatic SSH login identity. In this case, if you try ssh machine_name, the system complains about the incorrect permissions and asks for a password. In other words, it is best not to give any permissions at all for group/other if you want to enable automatic login.

To enable login without any user input, at initial SSH usage (after the SSH environment is set up) you need to add the node machine name to the known_hosts file under the /.ssh directory as follows:
Type the following:

ssh machine_name

You will be prompted with a Yes/No question whether to add machine_name to the known_hosts file.

Answer Yes.

You will now be able to log in without any input.

To verify that SSH is set up correctly, SSH to each host in the cluster before trying to run the management tool for HADB.

You are automatically logged in without a password requirement.

SSH for Mounted Home Directories

To implement SSH in systems with mounted home directories:

Verify that SSH requirements have been met as specified in SSH Requirements and Limitations
Log in to host as the HADB user.
Generate your keys by running the following:

ssh-keygen -t dsa

For SSH1 and OpenSSH/1, you do not need to give any parameters to the ssh-keygen command.

For the next three prompts, accept the default options by pressing Enter.

A file called identity.pub or id_dsa.pub (depends on whether you are using SSH version 1 or version 2) located in your ~/.ssh directory holds the public key. To connect to a machine without being asked for a password, the content of this file must be appended to a file called authorized_keys2 on all the machines. This can be done as follows:

To set up login identity, go to your user directory:

~/.ssh.

For SSH1, OpenSSH/1—Copy the identity.pub file and name it authorized_keys.

For OpenSSH/2—Copy the id_dsa.pub file and name it authorized_keys.

Verify that the .ssh directory and the .ssh/authorized_keys file do not have write permissions for group and other.

If necessary, disable these group/other write permissions as follows:

chmod og-w ~/.ssh
chmod og-w ~/.ssh/authorized_keys
chmod og-w /$HOME

Replace HOME with the home directory of the HADB user. For example:

chmod og-w ~/johnsmith.

Note	If the files under the ~/.ssh directory have even read permission given to group/other, you cannot set up an automatic SSH login identity. In this case, if you try to run ssh machine_name, the system complains about incorrect permissions and asks for a password. Consequently, it is best not to give any permissions for group/other if you want to enable automatic login.

To enable login without any user input, at initial SSH usage (after the SSH environment is set up) add the node machine name to the known_hosts file under the /.ssh directory:

ssh machine_name

When queried about whether or not to add machine_name to the known_hosts file, answer Yes.You will now be able to log in without any input.

To verify that SSH is set up correctly, SSH to each host in the cluster before trying to run the management tool for HADB.

You are automatically logged in without a password requirement.

Using HADB with Veritas file system on Solaris

When using Veritas file system on Solaris, you might get the message WRN: Direct disk I/O mapping failed in the HADB history files.

This message indicates that HADB is unable to turn on direct I/O for the data and log devices. Direct I/O is a performance enhancement that reduces the CPU cost of writing disk pages, and also causes less overhead of administering dirty data pages in the operating system.

To use direct I/O with Veritas, you should create the data and log devices on a file system that is mounted with the option mincache=direct. Note that this option will apply to all files created on the file system. For details, see the command mount_vxfs(1M).

An alternative is to use the Veritas Quick I/O facility. In effect, this product makes it possible to perform raw I/O to file system files. For more information, see the Veritas document, VERITAS File System™ 4.0 Administrator’s Guide for Solaris.

Note	This description is based on available documentation only. Sun Database Technology Group has not tested these configurations.

Using HADB With ext Filesystem on Linux

HADB does not support ext3 filesystem on Red Hat Advanced Server 2.1. Only ext2 is supported. ext3 filesystem is supported by HADB on Red Hat Advanced Server 3.0.

---

Setting Up the User Environment

Note	The procedures mentioned in this chapter contain UNIX specific examples. Except where indicated, the same commands and examples, with appropriate modifications, are applicable for Microsoft Windows platforms.

After you have set up host communication, you can run the hadbm command from the install_dir/SUNWhadb/4/bin directory location as follows:

./hadbm

However, it is much more convenient to set up your local environment to use the high-availability management client commands from anywhere. To set this up, perform the following steps.

Note	The examples in this section apply to using csh. If you are using another shell, refer to the man page for your shell for instructions on setting variables.

Set the PATH variable:

setenv PATH ${PATH}:install_dir/bin:install_dir/SUNWhadb/4/bin

Verify that the PATH settings are correct by running the following commands:

which asadmin
which hadbm

If multiple Java versions are installed, ensure that the JAVA_HOME environment is accessing JDK version 1.4.2_05 for Enterprise Edition.

setenv JAVA_HOME java_install_dir
setenv PATH ${PATH}:${JAVA_HOME}/bin

If your HADB device files and log files are not in the default location (appserver_install_dir/SUNWhadb/4) ,use the following hadbm command to locate these important files:

hadbm get configpath
hadbm get devicepath
hadbm get historypath
hadbm get installpath

Backup the locations listed by these commands.

---

Setting Up Administration for Non-Root

By default, during the initial installation or setup of the Sun Java System Application Server, write permissions of the files and paths created for Sun Java System Application Server are given to root only. For a user other than root to create or manage the Sun Java System Application Server, write permissions on the associated files must be given to that specific user, or to a group to which the user belongs. The files that are affected are (with their default locations):

Sun Java System Application Server configuration files—install_config_dir/cl*.conf
Sun Java System Application Servers setup and administration scripts— install_dir/bin/cl*
HADB binaries—install_dir/SUNWhadb
HADB configuration—/etc/opt/SUNWhadb
clsetup log file location—/var/tmp

You can create a user group for managing the Sun Java System Application Server as described in the following procedure. (An alternate approach is to set permissions and ownership for the specific user.)

To create a Sun Java System Application Server user group and set permissions on the installation root directory, repeat the following process for each affected file:

Log in as root.
From the command prompt, create the Sun Java System Application Server user group. For example:

# groupadd sjsasuser

You can type groupadd at the command line to see appropriate usage.

Change the group ownership for each affected file to the newly-created group. For example:

chgrp -R sjsasuser install_config_dir/cl*.conf

Set the write permission for the newly-created group:

chmod -R g+rw install_config_dir/cl*.conf

Repeat steps 3 and 4 for each affected file.
Make the clsetup and cladmin commands executable by the newly-created group. For example:

chmod -R g+x install_dir/bin/cl*

Delete and recreate the default domain, domain1, using the --sysuser option. The sysuser must also belong to the newly-created group. For example:

asadmin delete-domain domain1

asadmin create-domain --sysuser bleonard --adminport 4848 --adminuser admin --adminpassword password domain1

---

Using clsetup

The purpose of the clsetup utility is to automate the process of setting up a basic cluster in a typical configuration. The clsetup command is located in install_dir/bin, where install_dir is the directory where the Sun Java System Application Server software is installed.

The clsetup utility is bundled with the Sun Java System Application Server software along with the cladmin utility.

Note	The cladmin command is used to streamline the process of configuring and administering the cluster after all installation and configuration tasks are complete. Refer to the Sun Java System Application Server Administration Guide for instructions on creating the HADB and on using the cladmin command.

The following topics are addressed:

How clsetup Works
clsetup Requirements and Limitations
Editing the clsetup Input Files
Running clsetup
Cleanup Procedures for clsetup

How clsetup Works

The clsetup utility is a set of Sun Java System Application Server commands that allow a cluster to be configured automatically, based on prepopulated input files. As part of cluster setup, an HADB is created. However, you must set up your working cluster using the hadbm commands as described in the Sun Java System Application Server Administration Guide.

Note	The clsetup utility interface is unstable. An unstable interface may be experimental or transitional, and may therefore change incompatibly, be removed, or be replaced by a more stable interface in the next release.

The following topics are addressed in this section:

How the Input Files Work
What clsetup Accomplishes
Commands Used by clsetup

How the Input Files Work

Three input files are used by the clsetup utility to configure the cluster:

clinstance.conf—This file is pre-populated with information about application server instances server1 and server2. Refer to The clinstance.conf File for information on the contents of this file.
clpassword.conf—This file is pre-populated with the Admin Server password for domain1, which you provided when you installed the Sun Java System Application Server 7.1 Enterprise Edition software. Refer to The clpassword.conf File for information on the contents of this file.
clresource.conf—This file is pre-populated with information about the cluster resources: HADB, JDBC connection pool, JDBC resource, and session store and persistence. Refer to The clresource.conf File for information on the contents of this file.

Note	The configuration parameters required to set up the cluster are always read from the input files, and cannot be supplied through the command line.

Use the clsetup configuration parameters as they are preconfigured to set up a typical cluster configuration. To support a different configuration, make edits to any or all of the configuration files.

What clsetup Accomplishes

Using the pre-populated values in the clsetup input files, the clsetup utility command:

Creates a new server instance named server2 in the default domain named domain1. The HTTP port number for server2 is the next sequential number after the HTTP port number specified for server1 during installation (for example, if port number 80 is provided for server1 during installation, the port number for server2 is 81).
Creates the HADB named hadb with two nodes on the local machine. The port base is 15200, and the database password is password.
Creates the HADB tables required to store session information in the HADB.
Creates a connection pool named appservCPL in all the instances listed in the clinstance.conf file (server1, server2).
Creates a JDBC resource named jdbc/hastore in all the instances listed in the clinstance.conf file (server1, server2).
Configures the session persistence information in all the instances listed in the clinstance.conf file (server1, server2).
Configures an RMI/IIOP cluster in all the instances listed in the clinstance.conf file (server1, server2); thereby enabling RMI/IIOP failover.
Configures SFSB failover in all the instances listed in the clinstance.conf file (server1, server2).
Enables high availability in all the instances listed in the clinstance.conf file (server1, server2).

Note	Because the clresource.conf and clpassword.conf input files store passwords, they are access-protected with 0600 permissions.

Commands Used by clsetup

The clsetup utility uses a number of hadbm and asadmin commands to set up the cluster. In Table 2-1, the clsetup task is described in the left column and the command used to accomplish the task is listed in the right column.

Table 2-1  hadbm and asadmin Commands Used by the clsetup Utility

Task Performed by clsetup	Command
Checks to see if database exists.	hadbm status
Creates and starts the HADB.	hadbm create
Gets the JDBC URL.	hadbm get jdbcURL
Creates the session store.	asadmin create-session-store
Checks the instance status.	asadmin show-instance-status
Creates the instance.	asadmin create-instance
Creates the JDBC connection pool.	asadmin create-jdbc-connection-pool
Registers the data source.	asadmin create-jdbc-resource
Configures the persistence type	asadmin configure-session-persistence
Configures RMI/IIOP failover	asadmin add-iiop-cluster-endpoint
Configures SFSB failover	asadmin set
Reconfigures the instance.	asadmin reconfig -u admin

clsetup Requirements and Limitations

The following requirements and limitations apply to the clsetup utility:

The install paths, device paths, configuration paths, and so on must be the same on all machines that are part of the cluster.
Before you can use clsetup, the asadmin and hadbm utilities must be available on the local machine. clsetup can only be run on a machine where the following are installed:
The Sun Java System Application Server component or the Sun Java System Application Server Administration Client component
The HADB component or the HADB Management Client component
Before you can use clsetup, configure shared memory for UNIX platforms as described in Configuring Shared Memory and Semaphores. The clsetup utility does not set any shared memory values.

This procedure is not required on Windows platforms.

Before you can use the clsetup utility, set up the HADB cluster host communication for SSH or RSH (on UNIX platforms) as described in Setting Up Host Communication.

This procedure is not required on Windows platforms.

If you are using RSH (which is not the default), uncomment the following line in the clresource.conf file:

#set managementProtocol=rsh

If you are co-locating the Application Server and the HADB on the same machine using SSH, a known_hosts file must exist under the .ssh directory. If it does not, run either the ssh localhost or the ssh hostname command before using clsetup.
Before running clsetup, start the Admin Servers of all the Sun Java System Application Server instances that are part of the cluster.
The administrator password must be the same for all domains that are part of the cluster.
If the entities to be handled (HADB nodes and Application Server instances) already exist, clsetup does not delete or reconfigure them, and the respective configuration steps are skipped.
The values specified in the input files will be the same for all the instances in a cluster. clsetup is not designed to set up instances with different values. For example, clsetup cannot create a JDBC connection pool with different settings for each instance.
clsetup does not perform any inetd configuration; the HADB is created with no inetd settings. Instructions for performing inetd configuration are contained in the Sun Java System Application Server Administration Guide.

This configuration is not required on Windows platform.

Host names in the shell initialization files—If prompts are included with host names in your .cshrc or .login files, clsetup may appear to hang. Remove any prompts and excess output in any remote command invocations. For example, running the hostname command on hostB should print hostB without a prompt.
To run clsetup as a user other than root, follow the steps described in Setting Up Administration for Non-Root.

Editing the clsetup Input Files

The input files that are needed for the clsetup command are installed under the configuration installation directory, (by default /etc/opt/SUNWappserver7 on UNIX and c:\Sun\AppServer7\config\ on Windows), as part of the installation procedure. These input files are pre-populated with the values to set up a typical configuration, you can edit them as needed for your configuration.

This section addresses:

The clinstance.conf File
The clpassword.conf File
The clresource.conf File

The clinstance.conf File

For clsetup to work, all application server instances that are part of a cluster must be defined in the clinstance.conf file. During installation, a clinstance.conf file is created with entries for two instances. If you add more instances to the cluster, you must add information about these additional instances as follows:

# Comment

instancename instance_name
user user_name
host localhost
port admin_port_number
domain domain_n
instanceport instance_port_number

One set of entries is required for each instance that is part of the cluster. Any line that starts with a hash mark (#) is treated as a comment.

Note	The order in which these entries appear in the clinstance.conf file is important and must not be changed from the order specified here. If you add information about more application server instances, entries for these instances must appear in the same order. Comments can be added anywhere in the file.

Table 2-2 provides information about the entries in the clinstance.conf file. The left column contains the parameter name, the middle column defines the parameter, and the right column contains the default value.

Table 2-2  Entries in the clinstance.conf File 

Parameter	Definition	Default Value
instancename	Application Server instance name	server1, server2
user	Admin Server user name	admin
host	Host name	localhost
port	Admin Server port number	4848
domain	Administrative domain name	domain1
instanceport	Application Server instance port	80, 81
master	Master instance (used for cluster verification)	false

Example clinstance.conf File

This clinstance.conf file contains information about two instances.

#Instance 1

instancename server1
user admin
host localhost
port 4848
domain domain1
instanceport 80

#Instance 2

instancename server2
user admin
host localhost
port 4848
domain domain1
instanceport 81

The clpassword.conf File

When clsetup runs, it launches the asadmin command which needs the Admin Server password specified in the clpassword.conf file during installation.

The format of the clpassword.conf file is as follows:

AS_ADMIN_PASSWORD= password

where password is the Admin Server password.

Permissions 0600 are preset on the clpassword.conf file, which can only be accessed by the root user.

The clresource.conf File

During installation, the clresource.conf file is created to set up a typical configuration. The clresource.conf file contains information about the following resources that are part of the cluster:

HADB
Session store
JDBC connection pool
JDBC resource
Session persistence

On UNIX platforms, permissions 0600 are preset on the clresource.conf file, which can only be accessed by the root user.

Note	Before running clsetup, the values specified in the clresource.conf file can be modified for optimization, or for setting up a different configuration. If you edit the values, make sure that the order and format of the file is not changed. Any line that begins with a hash mark (#) is treated as a comment.

The parameters of the clresource.conf file are described in the following tables. The left column contains the parameter name, the middle column defines the parameter, and the right column contains the default value.

Table 2-3 describes the HADB parameters in the clresource.conf File.

Table 2-3  HADB Parameters in the clresource.conf File 

Parameter	Definition	Default Value
historypath	Path for the history files.	/var/tmp On Windows: REPLACEDIR (REPLACEDIR is replaced by the actual URL at runtime.)
devicepath	Path for the data and log devices.	/opt/SUNWappserver7/SUNWhadb/4 On Windows: C:\Sun\AppServer7\SUNWhadb\4.4.0-14
datadevices	Number of data devices on each node.	1
portbase	Port base number used for node 0. Other nodes are then assigned port number bases in increments of 20 from the number specified here (a random number in the range 10000 - 63000).	15200
spares	Number of spare nodes.	0
set	Comma-separated list of database configuration attributes.	For explanations of valid database configuration attributes, see Sun Java System Application Server 7.1 Administration Guide. For example, to specify the use of RSH instead of SSH (the default), uncomment the following line: #set managementProtocol=rsh
inetd	Indicates if HADB runs with the inet daemon. Not applicable on Windows plarform.	false
inetdsetupdir	Directory where theinet daemon setup files will be put. Not applicable on Windows plarform.	/tmp
devicesize	Size of device in MB. This size is applicable to all devices.	512
dbpassword	Password for the HADB user.	password
hosts	All hosts used for all data nodes.	Values are populated automatically based on the hosts specified during installation.

The database name is specified at the end of the [HADBINFO] section in the clresource.conf file.

Table 2-4 describes the session store parameters in the clresource.conf file.

Table 2-4  Session Store Parameters in the clresource.conf File 

Parameter	Definition	Default Value
storeurl	URL of the HADB store	REPLACEURL NOTE: Value is replaced by actual URL at runtime.
storeuser	User who has access to the session store	appservusr NOTE: Must match the username property in Table 2-5.
storepassword	Password for the storeuser	password NOTE: Must match the password property in Table 2-5.
dbsystempassword	Password for the HADB system user	password
adminpassword	The administrator password to manage the domain. If you use the adminpassword option with hadbm createdomain or hadbm create, then you must enter this password each time you use any hadbm command. (On Windows only)	none
adminpasswordfile	Use the adminpasswordfile option to provide the password as a path to a file that contains the password (On Windows only)	None
no-adminauthentication	The --no-adminauthentication option allows the administrator to use all hadbm commands without providing the administrator’s password. (On Windows only)	None

Table 2-5 describes the JDBC connection pool parameters in the clresource.conf file.

Table 2-5  JDBC Connection Pool Parameters in the clresource.conf File 

Parameter	Definition	Default Value
steadypoolsize	Minimum and initial number of connections maintained in the pool.	8
maxpoolsize	Maximum number of connections that can be created.	32
datasourceclassname	Name of the vendor-supplied JDBC datasource. Name of the vendor-supplied JDBC datasources capable datasource class will implement javax.sql.XADatasource interface. Non-XA or Local transactions only datasources will implement javax.sql.Datasource interface.	com.sun.hadb.jdbc.ds.HadbDataSource
isolationlevel	Specifies the transaction isolation level on the pooled database connections.	repeatable-read
isisolationguaranteed	Transaction isolation level guaranteed	true
validationmethod	Specifies the type of validation method.	meta-data
property	Property used to specify username, password, and resource configuration.	username=appservusr:password=password:cacheDataBaseMetaData=false:eliminateRedundantEndTransaction=true:serverList=REPLACEURL NOTE: Make sure that the username and password properties use the same values as shown in the Session Store Parameters table. REPLACEURL is replaced by the actual URL at runtime.)

The connection pool name is specified at the end of the [JDBC_CONNECTION_POOL] section in the clresource.conf file.

Table 2-6 describes the JDBC resource parameters in the clresource.conf file.

Table 2-6  JDBC Resource Parameters in the clresource.conf File 

Parameter	Definition	Default Value
connectionpoolid	Name of the connection pool	appservCPL NOTE: Connection pool name is specified in Table 2-5.

The JDBC resource name is defined at the end of the [JDBC_RESOURCE] section in the clresource.conf file.

Table 2-7 describes the session persistence parameters in the clresource.conf file.

Table 2-7  Session Persistence Parameters in the clresource.conf File 

Parameter	Definition	Default Value
type	Session persistence type	ha
frequency	Session frequency	web-method
scope	Session scope	session
store	Session store	jdbc/hastore NOTE: Store name is defined at end of the [JDBC_RESOURCE] section.

Table 2-8 describes the stateful session bean parameter in the clresource.conf file.

Table 2-8  Stateful Session Bean Parameters in the clresource.conf File 

Parameter	Definition	Default Value
sfsb	Stateful session bean failover	false

Table 2-9 describes the RMI/IIOP failover parameter in the clresource.conf file.

Table 2-9  RMI/IIOP Failover Parameters in the clresource.conf File 

Parameter	Definition	Default Value
rmi_iiop	RMI/IIOP cluster configuration	false

Table 2-10 describes the cluster identification parameter in the clresource.conf file.

Table 2-10  Cluster Identification Parameters in the clresource.conf File 

Parameter	Definition	Default Value
cluster_id	Cluster ID	cluster1

Example clresource.conf File on UNIX

[HADBINFO]
historypath /var/tmp
devicepath /opt/SUNWappserver7/SUNWhadb/4
datadevices 1
portbase 15200
spares 0
#set    managementProtocol=rsh
inetd false
inetdsetupdir /tmp
devicesize 512
dbpassword password
hosts machine1,machine1
hadb

[SESSION_STORE]
storeurl                 REPLACEURL
storeuser              appservusr
storepassword             password
dbsystempassword        password

[JDBC_CONNECTION_POOL]
steadypoolsize         8
maxpoolsize         32
datasourceclassname     com.sun.hadb.jdbc.ds.HadbDataSource
isolationlevel          repeatable-read
validationmethod        meta-data
property username=appservusr:password=password:cacheDataBaseMetaData=false:eliminat eRedundantEndTransaction=true:serverList=REPLACEURL

appservCPL

[JDBC_RESOURCE]
connectionpoolid      appservCPL
jdbc/hastore

[SESSION_PERSISTENCE]
type       ha
frequency  web-method
scope      session
store      jdbc/hastore

Example clresource.conf file on Windows

[HADBINFO]

package V4.4

historypath   REPLACEDIR

devicepath    C:\Sun\AppServer7\SUNWhadb\4.4.0-12

datadevices    1

portbase    15200

spares    0

#set    LogbufferSize=32,DataBufferPoolSize=128

devicesize    208

dbpassword    password

hosts    machine1,machine2

adminpassword    password

hadb

[SESSION_STORE]

storeurl    EPLACEURL

storeuser    appservusr

storepassword    password

dbsystempassword    password

[JDBC_CONNECTION_POOL]

steadypoolsize    8

maxpoolsize    2

datasourceclassname    com.sun.hadb.jdbc.ds.HadbDataSource

isolationlevel     repeatable-read

--isisolationguaranteed=true

validationmethod    meta-data

property    username=appservusr:password=password:cacheDataBaseMetaData=fa lse:eliminateRedundantEndTransaction=true:serverList=REPLACEURL

appservCPL

[JDBC_RESOURCE]

connectionpoolid    appservCPL

jdbc/hastore

[SESSION_PERSISTENCE]

type    ha

frequency    web-method

scope    session

store    jdbc/hastore

[EJB_FAILOVER]

sfsb    true

[RMI_IIOP_FAILOVER]

rmi_iiop    true

[CLUSTER_ID]

cluster_id    cluster1

Running clsetup

The syntax for running clsetup is as follows:

clsetup [--help] [--instancefile instance_file_location] [--resourcefile resource_file_location] [--passwordfile password_file_location] verify

If no arguments are specified, clsetup assumes the following defaults:

--instancefile is install_config_dir/clinstance.conf

--resourcefile is install_config_dir/clresource.conf

--passwordfile is install_config_dir/clpassword.conf

You can override these arguments by providing custom input file locations. For example:

./clsetup --resourcefile /tmp/myappservresource.conf

When providing custom input files, follow the required format found in the input files. For information on doing this, see "Editing the clsetup Input Files," on page 57.

To run clsetup:

Verify that the requirements have been met as described in clsetup Requirements and Limitations.

Note	If you want to run clsetup as a user other than root, see Setting Up Administration for Non-Root to set this up.

Verify that the input files have the required information to set up the cluster. If necessary, edit the input files following the guidelines in Editing the clsetup Input Files.
If you are using RSH, edit the clresource.conf file to uncomment the following line (remove the # sign): #set managementProtocol
Go to the Sun Java System Application Server installation /bin directory.
Invoke the clsetup command:

On Unix:./clsetup

On Windows: clsetup.bat

The clsetup command runs in verbose mode. The various commands are displayed on the screen as they run, and the output is redirected to the log file, /var/tmp/clsetup.log (on UNIX) or the default Windows temp directory (on Windows).

If a vital error occurs, the configuration stops and the error is recorded in the log file. If the log file already exists, the output is appended to the existing log file.

If the entities to be handled (HADB nodes and Application Server instances) already exist, clsetup does not delete or reconfigure them, and the respective configuration steps are skipped. This type of event is recorded in the log file.

When clsetup completes the configuration, scan the log file after each run to review the setup.
Upon completion, clsetup returns the exit codes described in Table 2-11:

Table 2-11  Exit Codes for the clsetup Command 

Exit Code	Description
0	Successful exit
2	Usage error
3	Instance file not found
4	Instance file cannot be read
5	Resource file not found
6	Resource file cannot be read
7	Password file not found
8	Password file cannot be read
10	Script cannot find asadmin
11	Script cannot find hadbm
12	Cannot create temporary file
13	Session store configuration failed
14	Create HADB failed
15	HADB get jdbcURL failed
16	User exits in welcome message

Cleanup Procedures for clsetup

After running clsetup, errors that have occurred are logged in the log file /var/tmp/clsetup.log. Examine the log file after every run of the clsetup command and correct any significant errors that are reported (for example, failure to create a non-existing instance).

You can undo all or part of the configuration as follows:

To delete an Application Server instance: asadmin delete-instance instance_name
To delete the HADB:
hadbm stop database_name
hadbm delete database_name
To clear the session store: cladmin clear-session-store --storeurl URL_information --storeuser storeUsername --storepassword store_user_name
To delete the JDBC connection pool: asadmin delete-jdbc-connection-pool connectionpool_name
To delete the JDBC resource: cladmin delete-jdbc-resource JDBCresource_Name

See the Man pages for detailed examples of each of these commands. You are now ready to proceed to the Sun Java System Application Server Administration Guide for instructions on configuring the HADB and managing the cluster, the load balancer plug-in, and the HADB.

---

Time Synchronization

It is strongly recommended to synchronize the clocks on the hosts running HADB because HADB uses time stamps based on the system clock for debugging purposes as well as for controlling internal events. The events are written out to history files prefixed by time stamps. Since HADB is a distributed system, the history files from all HADB nodes are analyzed together in troubleshooting. HADB also uses the system clock internally for managing time dependent events like timeouts.

Adjust the system clock on a running HADB system is not recommended. HADB has been implemented to handle this in general, but you should note the following points:

Problems in the operating system or other software components on the hosts might cause problems for the whole system when the clock is adjusted. Typical problems are hangs or restarts of nodes.
Adjusting the clock backward may cause some of the HADB server processes to hang for a period of time as the clock was adjusted. Adjusting the time forward does not exhibit the same problem.

To synchronize clocks, e.g., “xntpd” (network time protocol daemon) in Solaris and “ntpd” in Linux can be used.

Previous      Contents      Index      Next

---

Copyright 2004 Sun Microsystems, Inc. All rights reserved.