| Sun ONE Application Server 7, Enterprise Edition Administrator's Guide |
Chapter 19
Using the cladmin CommandThis chapter describes the use of the cladmin command that is part of the SunTM Open Net Environment (Sun ONE) Application Server 7, Enterprise Edition.
This chapter contains the following sections:
About the cladmin CommandYou can use the cladmin command to run certain asadmin commands simultaneously on all application server instances in a cluster. For example, you can use this command to start all instances in a cluster or to deploy a web application to all instances in a cluster. This simplifies the task of cluster administration
Note
Only the asadmin commands listed in "asadmin Commands Supported by the cladmin Command" have been tested and are supported although other asadmin commands should work.
It is recommended that to configure the application server instances in a cluster, you use the cladmin command for all the supported asadmin commands. This will ensure consistency in configuration of all application server instances in the cluster.
The cladmin command needs input files for its functioning. The information about application server instances is stored in the clinstance.conf file and the information about password is stored in the clpassword.conf file. You can modify the input files to support different configurations. Both the input files are text files. More information about the input files is provided in "Input Files for the cladmin Command".
The command reads the instance-specific information from the clinstance.conf file one instance at a time. You supply the rest of the argument to the cladmin command. The cladmin command invokes the corresponding asadmin command on each instance specified in the clinstance.conf file.
The command is located in install_dir/bin where install_dir is the location of the Sun One Application Server installation directory. The input files are located in the configuration directory of the Sun One Application Server. The default location of the configuration directory is /etc/opt/SUNWappserver7.
This topic contains the following sections:
asadmin Commands Supported by the cladmin Command
The following table lists asadmin commands that you can run simultaneously for each application server instance in a cluster using the cladmin command. In the table, the left column lists the asadmin command and the right column lists the purpose of the command.
Requirements and Limitations
Here are important facts that you must know about the use of cladmin command:
- All instances that are part of the cluster must have the same user name and password for the administrator.
- Before running the command you must start the administration servers of all application server instances that are part of the cluster.
- The values specified in the input files will be same for all the instances in a cluster. The cladmin command is not designed to setup each instance with different values. For example, this command cannot create a JDBC Connection Pool with different settings for each instance.
Input Files for the cladmin CommandThe input files that are needed for the cladmin command to function are:
This topic contains the following sections:
The clinstance.conf File
For the cladmin command to work properly, all application server instances that are part of a cluster must be defined in the clinstance.conf file
During standard installation, the installation program creates a clinstance.conf file with entries for two instances. The default values for these entries are provided in "Entries in the clinstance.conf file".
If you add more instances to the cluster, you must add information about these instances in the clinstance.conf file.
If you create more clusters, you must specify the information about the instances in each cluster in a separate clinstance.conf file.
The format of the clisntance.conf file is described here. One set of entries is required for each instance that is part of the cluster. Any entry that has # as the first character is treated as a comment.
# Comment
instancename Instance Name
user User Name
host localhost
port Admin Port Number
domain Domain Name
instanceport Instance Port Number
The following table provides information about each possible entry in the clinstance.conf file, its meaning, and its default value. The default value is the value specified by the installation program during a standard installation for the two entries that it creates.
In the table, the left column lists the entry in the clinstance.conf file, the middle column provides the definition of the entry, and the right column lists the default value(s) of the entry.
Here is a sample clinstance.conf file with 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
The clpassword.conf file contains the administration server password. Whenever during the execution of the cladmin command, the asadmin command requires the administration server password, the password specified in the clpassword.conf file is used.
The format of the clpassword.conf file is as follows:
AS_ADMIN_PASSWORD= password
where password is the administration server password.
Note
Permissions 0600 are preset on the clpassword.conf file and the file can be accessed only by the root user.
Running the cladmin CommandBefore running the cladmin command:
The syntax of the cladmin command is as follows:
./cladmin [--help] [--instancefile instance_file_location] [--passwordfile password_file_location] asadmin_command
where:
- instance_file_location is the location of the input file clinstance.conf
- password_file_location is the location of the input file clpassword.conf
- asadmin_command is the asadmin command that you want to run on the application server instances in the cluster.
Note
The input files clinstance.conf and clpassword.conf must follow the required format as specified in "Input Files for the cladmin Command".
If the input files are located in the Configuration directory of the Sun ONE Application Server (by default /etc/opt/SUNWappserver7), you can omit the instancefile and passwordfile options and run the command as follows:
./cladmin asadmin_command
In this case, the input files will be read from the configuration directory of the Sun ONE Application Server.
Example: Starting All Instances in a Cluster
./cladmin start-instance
Because the location of the input files has not been specified, the input files are read from the Configuration directory of the Sun ONE Application Server (by default /etc/opt/SUNWappserver7)
Example: Starting All Instances in a Cluster with Location of Input Files Specified
./cladmin --instancefile /tmp/clinstance.conf --passwordfile /tmp/clpassword.conf start-instance
Example: Creating a JDBC Connection Pool Named CluJDBC for All Instances in a Cluster
./cladmin create-jdbc-connection-pool --user admin --datasourceclassname com.sun.hadb.jdbc.ds.HadbDataSource --isisolationguaranteed=true --isolationlevel repeatable-read --isconnectvalidatereq=true --validationmethod auto-commit --failconnection=false --property username=hadbuser:password=hadbpassword:serverList=exampleserver 1.example.com\:15100,exampleserver2.example.com\:15120 CluJDBC
Example: Configuring Session Persistence for all Instances in a Cluster
./cladmin configure-session-persistence --user admin --type ha --frequency web-method --scope session --store jdbc_hastore
Messages
The command returns exit codes that will help you in getting information about the command execution. The exit codes can be obtained by running
echo $?
from the command line immediately after running the cladmin command.
The exit codes are described in the following table. In the table, the left column lists the exit code and the right column lists the description of the exit code.
Log file for the cladmin Command
The log file is named cladmin.log and is available in the directory /var/tmp/cladmin.log
At the end of every execution, you are advised about the location of the log file. It is recommended that you scan the log file after each run.
By default the cladmin command executes in the verbose mode and logs all the information in the log file. Log file entries start and end with timestamp tags. If the log file exists prior to execution of the command, the output is appended to the existing log file.
Using the cladmin Command While Running Multiple ClustersIf you are running multiple clusters, you must specify a separate clinstance.conf file for each cluster.
You can run the cladmin command on the instances in any particular cluster by specifying the path of the input files for that particular cluster as explained in "Running the cladmin Command".
