The tc Server Command Line Interface

Overview of the tcsadmin Command-Line Interface

SpringSource tc Server provides a command-line interface (CLI) called tcsadmin that you can use to perform a subset of tc Server configuration and application deployment tasks. You can use the CLI to configure and manage both single tc Server instances or groups of tc Servers.

The tcsadmin CLI is the script version of the HTML-based AMS tool. When you run the various CLI commands, you must specify an AMS server using its hostname and port; this means means that you must install the AMS component of tc Server in order to use the CLI.

You can use tcsadmin to perform the following tasks; all tasks are within the context of a particular AMS server:

• List the known tc Servers instances, tc Server groups, and members of a group.
• Create a group of tc Servers.
• List the applications deployed to a tc Server instance or tc Server group and the current status of the applications.
• Upload and deploy an application to a tc Server instance or group.
• Start, stop, reload, or undeploy an application to a tc Server instance or group.
• Modify the configuration of a tc Server instance or group.
• Upload a server.xml file to a tc Server instance or group.
• Download the configuration of a tc Server instance or group and write it to a file.
• Start, stop, or restart a tc Server instance or all servers in a group.

When you use the tcsadmin CLI to perform application management and configuration operations for a group of tc Server instances, the CLI performs the operations sequentially and synchronously. For example, if you deploy a Web application to a group of tc Server instances, the CLI deploys the app to one of the server instances, waits for success, and only then deploys the application to another server in the group.

Any user configured to access the AMS UI console can also use the tcsadmin CLI. Additionally, all role-based access is honored for all tc Server operations, including server configuration, application management, and server control.

Tips for Windows Users

In this documentation, it is assumed that you are running the tcsadmin command-line interface on a Unix platform. If, however, you are running on Windows, the following changes to the documentation apply:

• Execute the Windows-specific tcsadmin.bat command rather than the Unix tcsadmin.sh command.
• Use back-slashes (\) instead of forward-slashes when specifying a directory path, as well as the standard Windows method for indicating disks, such as c:\home\springsource.
• Use quotation marks to enclose directory names that contain spaces. For example, --localpath="c:\home\My Web Apps\test.war".

Downloading the tc Server Command-Line Interface

You must download the tc Server command-line interface binaries onto each computer on which you want to run it, as described in the following procedure:

1. On the computer on which you want to download and install the tc Server command-line interface, invoke the AMS administration console in a browser. See the Getting Started with the AMS Console link in the left frame of the Getting Started with tc Server guide for details.

2. Click the Administration link at the top of the main AMS console page.

3. In the Plugins section, click the tc Server Command-line Interface link.

4. Click the springsource-ams-scripting-client.zip link and save the ZIP file to a temporary directory on your computer.

5. Unzip the file to the directory of your choice.

6. The tcsadmin.sh (Unix) and tcsadmin.bat (Windows) scripts are located in the springsource-ams-scripting-client-version/bin directory, where version refers to a version string, such as 2.0.0.RC3.

General Syntax of the tcsadmin Command-Line Interface

Use the following syntax when using the tcsadmin command-line interface:

tcsadmin.sh|bat command options connection-parameters

where:

• Unix users use the tcsadmin.sh command-line interface and Windows users use tcsadmin.bat.
• command refers to a specific command, such as start-application which starts an application that is deployed to a tc Server instance or group or modify-configuration to change the configuration of a tc Server instance or group. See List of Available Commands for a table that lists all available commands.
• options refers to one or more options for the specific command. These options take the form --optionname=value, such as --groupname=MyGroup1. The list of available options depends on the specified command.
• connection-parameters refers to the list of parameters that specify the AMS server to which the command-line interface connects. You can also specify the connection parameters in a file to avoid specifying the same parameters at the command-line. See Connection Parameters for details.

The following example shows how to start an application called myApp that is deployed to the tc Server group called Group1.

prompt$ ./tcsadmin.sh start-application --groupname=Group1 --application=myApp 

In the example, the command is start-application and the options are --groupname=Group1 and --application=myApp. Because there are no connection parameters specified at the command-line, it can be assumed that either the user running the command has created a user.home/.ams/client.properties file, or the default values of the connection parameters are adequate.

List of Available Commands

The following table lists all the available tcsadmin commands, along with the type of command and a brief description. The commands are broken into the following four types:

• Inventory: Commands for managing the AMS server's inventory, such as listing the known tc Servers and groups and creating new groups.
• Application Management: Commands for deploying applications to a tc Server instance or group, or managing already-deployed applications.
• Configuration: Commands for configuring tc Server instances or the members of a tc Server group.
• Control: Commands for starting, stopping, and restarting tc Server instances or groups.

Click on the name of the command in the table for complete reference, including its associated options and examples.

Connection Parameters

The tc Server command-line interface must connect to an AMS server to perform the work associated with a particular command. This means that each time you use the CLI, you must specify connection parameters that indicate the particular AMS server to which you want to connect.

You can specify these parameters on the command-line. You can also create a user.home/.ams/client.properties file that lists the parameters and their values to avoid having to specify the connection parameters with every command, where user.home refers to the home directory of the user running the command-line interface. NOTE that the .ams directory name starts with a dot. On Windows, the home directory of a user is c:\Documents and Settings\<user_name>.

Parameters specified at the command-line always take precedence over the client properties file; if the CLI does not find any value for a parameter, either at the command-line or in the client properties file, it uses the default value.

The following table lists these connection parameters and their default values:

The following example shows how to use these parameters on the command-line:

prompt$ ./tcsadmin.sh list-servers --host=localhost --port=7081 \
         --user=tc_user --password=super_secret --secure 

In the example, the CLI connects to an AMS server on the same computer on which the CLI is running. The AMS server is listening at the TCP/IP port 7081. The username and password of the user connecting to the AMS server are tc_user and super_secret, respectively. The CLI connects to the AMS server using SSL.

If you want to specify the same parameters in a file to avoid specifying them at the command line, you must create a file called client.properties in a .ams sub-directory of the home directory of the user running the CLI. The following example shows the structure of this file using the parameter values specified above:

host=localhost
port=7081
user=tc_user
password=super_secret 
secure=true

NOTE: Even though the --secure parameter does not take a value at the command line, it does take a Boolean value in the client.properties file: true to enable a secure connection, false otherwise.

The following example shows the same command from above, but without the connection parameters; the CLI reads the values from the user.home/.ams/client.properties file:

prompt$ ./tcsadmin.sh list-servers 

It is assumed in the remainder of the documentation that you have created a client.properties file that contains the connection parameters; this is so sample usage of the server configuration and application management commands is easier to read.

Using Special Characters as Parameter Values

Sometimes it is necessary to use special characters, such as a space or a meta character, as part of a parameter value. The following guidelines describe how to use these special characters:

• Enclose parameter values that contain spaces in quotation marks. For example:

  prompt> ./tcsadmin list-servers --platform="My Machine"

• On Unix, escape meta-characters by preceding them with a backslash (\). Unix meta-characters include the following: \ . ! $ % ^ & * | { } [ ] " ' ` ~ ; . . You must escape these characters on Unix platforms because they have special meaning in the shell. For example, to specify the name of an application that contains a pipe character, use the following syntax:

  prompt > ./tcsadmin start-application --groupname=Group1 --application=my\|app

• Be particularly careful with the set-jvm-options command, because its --options argument takes a comma-delimited set of JVM options. If one of the options themselves includes a comma, then be sure to escape it with a backslash; otherwise, the tcsadmin script will interpret it as a delimiter between a list of JVM options.

Group Command Behavior

You can run many of the tcsadmin commands against either a single tc Server instance or a group of tc Server instances. The following guidelines describe the behavior of commands if you run then against a group and a failure occurs:

• Group application deployment and configuration commands, such as deploy_application or put-file, happen sequentially and synchronously. This means, for example, that if you use tcsadmin to deploy a Web application to a group, the script deploys the application to one of the tc Servers in the group, waits for the deployment to succeed or fail, then deploys the application to another tc Server in the group, and so on until the script has attempted to deploy the application to all members of the group. You cannot specify the order of execution for the tc Servers in a group.

  If the script encounters a failure when deploying to one tc Server instance in the group, it reports the failure but then continues to deploy the application to any remaining tc Server instances in the group.

• Group control commands, such as start, also happen sequentially and synchronously, and you cannot specify the order in which the tc Server instances in the group start/stop/restart. However, if the script encounters a failure when starting/stopping/restarting a tc Server instance, the script stops all execution and does not continue to execute the command against any remaining tc Server instances. Any server control actions that have already happened are not rolled back.

  For example, assume a tc Server group includes five tc Server instances that are all currently stopped and you execute the start command against the group. Assume that two tc Server instances started successfully, but then the third encountered a problem and returned a failure. The script stops all execution. At that point, the first two tc Server instances are still started, and the remaining three are still stopped.

Exit Codes

Each time you execute tcsadmin, the script always returns an exit code that indicates the success or failure of the particular command you just ran. The script also outputs a descriptive status message to STDOUT.

The exit code for success is always 0; the exit code for failure is a non-zero positive integer. Typically, the failure exit code is 1 if a single failure happened. However, because some tcsadmin commands run against a tc Server group, the command might succeed for some tc Server instances in the group but fail for others. In this case, the exit code will equal the number of failures.

The detailed reference information for each tcsadmin command includes the expected exit codes for that particular command.

Getting Help

Use the following commands to get help about a particular command or the list of available commands:

prompt$ ./tcsadmin.sh help

The help command lists all the available commands along with their parameters.

prompt$ ./tcsadmin.sh command --help

Use the --help parameter with any specific command to get detailed information about that command. The following example shows how to get detailed information about the list-applications command:

prompt$ ./tcsadmin.sh list-applications --help