Previous Contents Index Next |
Sun Java System Application Server Standard and Enterprise Edition 7 2004Q2 Administration Guide

> ## Appendix F
> Using the cladmin Command for Administration (Enterprise Edition)

> This chapter describes the use of the cladmin command to administer Sun Java™ System Application Server clusters.

> This module contains the following sections:

> - About the cladmin Command
> - Cluster Operations Using cladmin Command
> - asadmin Commands Supported by cladmin
> - Requirements for Running the cladmin Command
> - Using cladmin Command
> - Limitations of cladmin Command

> ##

> About the cladmin Command

> You can use the cladmin command to run asadmin commands together 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.

> The cladmin command needs input files for its functioning. The instance-specific information is stored in the cinstance.conf file and the information about password is stored in the clpassword.conf file. You can customize the input files entries to support different configurations. Both the input files are text files. More information about the input files is provided in Using cladmin Command.

> The command reads the instance-specific information from the cinstance.conf file one instance at a time. You supply the rest of the argument to the asadmin command. The command will invoke the corresponding asadmin command on each instance specified in the cinstance.conf file.

> The command is located in InstallDir/bin where InstallDir is the location of the directory where Sun Java System Application Server is installed. The input files are located in the configuration directory of the Sun Java System Application Server. The default location of the configuration directory is etc/opt/SUNWappserver7.

> ##

> Cluster Operations Using cladmin Command

> You can perform the following operations on Application Server instances in a cluster using cladmin:

> - Start all instances in a cluster
> - Stop all instances in a cluster
> - Deploy an application to all Application Server instances in a cluster
> - Undeploy an application from all Application Server instances in a cluster
> - Create a JDBC resource for all Application Server instances in a cluster
> - Create a JDBC connection pool for all Application Server instances in a cluster
> - Configure session persistence for all Application Server instances in a cluster
> - Configure session persistence for all Application Server instances in a cluster
> - Delete the JDBC connection pool for all Application Server instances in a cluster
> - Delete the JDBC resource for all Application Server instances in a cluster

> ##

> asadmin Commands Supported by cladmin

> 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.

> Table F-1 asadmin Commands Supported for Use with cladmin Command

> Command | Use
> --- | ---
> start-instance | Starts the application server instance.
> stop-instance | Stops the application server instance.
> deploy | Deploys an EJB, WEB, connector, appclient, or application component that is in the directory to the application server instance.
> undeploy | Removes the deployed component from the application server instance.
> create-jdbc-resource | Creates a JDBC resource for the application server instance.
> create-jdbc-connection-pool | Creates a JDBC connection pool for the application server instance.
> configure-session-persistence | Configures session persistence for the application server instance.
> delete-jdbc-resource | Deletes the JDBC resource for the application server instance.
> delete-jdbc-connection-pool | Deletes the JDBC connection pool for the application server instance.

> ##

> Requirements for Running the cladmin Command

> You must meet the following requirements before using 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 should 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.
> - You must have performed the HADB shared memory set up and the HADB Cluster Host Communication Set up for SSH and RSH. For more information, see chapter, Post-installation Tasks, (or whatever it will be) in Sun Java System Application Server Installation Guide.

> ##

> Using cladmin Command

> This section describes the following topics:

> - Input Files for the cladmin Command
> - Running the cladmin Command
> - cladmin Status Messages
> - Log file for the cladmin Command

> ### Input Files for the cladmin Command

> The input files that are needed for the cladmin command to function are:

> - clinstance.conf File

> This file contains information about the Application Server instances that are part of the cluster

> - clpassword.conf File

> This file contains information about the asadmin password.

> #### 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.

> Caution | The order in which these entries appear in the clinstance.conf file is important and must not be changed from the order shown here. If you add information about more application server instances, entries for these instances must appear in the order shown here However, you can add comments anywhere in the file.

> # 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.

> Table F-2 Entries in the clinstance.conf File

> Entry | Definition | Default Value(s)
> --- | --- | ---
> Instance Name | Name of the application server instance | server1, server2
> User Name | Administration server user name | admin
> Localhost | Host name | localhost
> Admin Port Number | Port number of the Administration Server | 4848
> Domain Name | Name of the Administrative domain | domain1
> Instance Port Number | Port number of the application server instance | 80, 81

> 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

> #### clpassword.conf File

> The clpassword.conf file contains the administration server password. 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 asadmin password.

> If you ran the clsetup command as part of the post installation step, the clpassword.conf file would have been created and should be available in the configuration directory of the Sun Java System Application Server. The value of password will also be entered in the file. Permissions 0600 are preset on this file and the file can be accessed only by the root user.

> If you did not run the clsetup command as part of the post installation step, you must created this file manually and save it in the configuration directory of the Sun Java System Application Server. You must also enter the value for password and set appropriate permissions on the file.

> ### Running the cladmin Command

> Before running the cladmin command:

> - Make sure you list all the instances that are part of the cluster in the clinstance.conf file.
> - Change the directory to install_dir/bin where install_dir is the Sun Java System Application Server installation directory.

> 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 Using cladmin Command.

> If the input files are located in the Configuration directory of the Sun Java System 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 Java System Application Server.

> Code Example F-1 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 Java System Application Server (by default /etc/opt/SUNWappserver7)

> Code Example F-2 Example: Starting All Instances in a Cluster with Location of Input Files Specified

> ./cladmin --instancefile /tmp/clinstance.conf --passwordfile /tmp/clpassword.conf start-instance

> Code Example F-3 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

> Code Example F-4 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

> Note | If you are running multiple clusters, you must specify a separate clinstance.conf file for each cluster.

> ### cladmin Status 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.

> Table F-3 Exit Codes for the cladmin Command

> Exit Code | Description
> --- | ---
> 1 | Successful exit
> 2 | Syntax error
> 3 | Cannot find instance input file (clinstance.conf)
> 4 | Cannot read instance input file (clinstance.conf)
> 5 | Cannot find password input file (clpassword.conf)
> 6 | Cannot read password input file (clpassword.conf)
> 7 | User trying to run the command is not a root user
> 8 | Cannot locate asadmin command
> 9 | Cannot create temporary file
> 10 | Command could not be executed

> ### 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.

> ##

> Limitations of cladmin Command

> The following list describes the limitations of the cladmin command:

> - It does not perform any RSH or SSH configuration.
> - It does not perform any inetd configuration.
> - It does not set any shared memory values
> - Cleanup or undo scripts for the cladmin command are not provided.
> - If the entities to be handled (database nodes, connection pool, and so on) exist on the machine, the cladmin command does not delete or reconfigure them. The information is redirected to the log file and the respective configuration step are skipped.
> - The default input files are deleted as part of standard uninstallation. Therefore, if you want to retain the input files after uninstallation, you must back up these files before uninstallation.
> - The command does not administer the High Availability Database (HADB) or the loadbalancer plug-in. For more information, see Chapter 21, "Administering the High-Availability Database (Enterprise Edition)."

> Previous Contents Index Next

> Copyright 2004 Sun Microsystems, Inc. All rights reserved.