tc Runtime and Group Configuration Commands

This section documents the tcsadmin commands that you use to configure tc Runtime instances and groups. See also General Syntax of the tcsadmin Command-Line Interface.

Note

Every time you run the tcsadmin script, provide connection parameters that specify the HQ Server to which the script connects. Specify these connection parameters at the command-line or in a user.home/.hq/client.properties file, where user.home refers to your home directory. In this section of the documentation, it is assumed that you have created a client.properties file, so that examples are not cluttered with the same connection parameters and are thus easier to read. See Connection Parameters for detailed information about specifying the connection parameters at the command-line or in a file.

get-file

Get a configuration file from a single tc Runtime instance and write it to a file on the local computer on which you are running the tcsadmin script.

Although you can get any configuration file, typically you work only with the following files, relative to the CATALINA_BASE/conf directory:

  • server.xml

  • web.xml

  • context.xml

Exit codes: Returns 0 if successful and 1 on failure.

Table 25. Options of the get-file Command

OptionDescriptionRequired?
--servernameName of the tc Runtime Instance from which you want to get a configuration file.

Use list-servers to get the names of the tc Runtime Instances in the HQ inventory.

Specify --servername or --serverid, but not both.
--serveridID of the tc Runtime instance from which you want to get a configuration file.

Use list-servers to get the IDs of the tc Runtime instances in the HQ inventory.

Specify --servername or --serverid, but not both.
--fileName of the configuration file that you want to get from the tc Runtime instance, relative to its CATALINA_BASE directory. Typical values include conf/server.xml, conf/catalina.properties, conf/web.xml, or conf/context.xml.

Use forward or backward slash to specify directories; the slashes are resolved on the corresponding computer platform on which the command is eventually run.

Yes.
--targetfileName of the file, local to the computer on which you are running the tcsadmin script, to which you want the retrieved configuration to be written. If you enter a relative pathname, it is local to the working directory of the script, which by default is the top-level installation directory of the script, such as /usr/springsource-tcserver- scripting-client-2.1.X.RELEASE.Yes.

The example gets a server.xml configuration file from a tc Runtime instance with ID 10045 and writes it to a local file called /tmp/group-server.xml:

prompt$ ./tcsadmin get-file --serverid=10045 --targetfile=/tmp/group-server.xml --file=conf/server.xml

put-file

Push a single tc Runtime instance configuration file to a tc Runtime instance or group of servers.

In this context, the term push refers to copying any configuration file to the tc Runtime instance directory. Although you can push any configuration file, typically you work only with the following files, relative to the CATALINA_BASE/conf directory:

  • server.xml

  • web.xml

  • context.xml

  • catalina.properties

When you execute this command to push a new copy of a particular configuration file, the tcsadmin script creates a backup of the existing file in the corresponding conf directory with the name file_name.yyyy-mm-dd.hh-mm-ss to facilitate manual rollback. If an error occurs writing any of the files, the tcsadmin script rolls back all file writes. If you execute this command against a group, this file backup happens for each member of the group. You can disable the creation of the backup file with the --nobackupfile option.

When you push a configuration file to a group of tc Runtime instances, SpringSource highly recommends that you use templated files. This means that the file uses variables for configuration values that vary from server to server, such as the HTTP listen port; then, the catalina.properties file for each server contains the actual values which tc Runtime substitutes for the variables at runtime. The default server.xml file for tc Runtime instances uses templates, which means that you can use the get-file command to get a server.xml file for a particular tc Runtime instance and use it as a template for pushing configuration changes to a group, or even another tc Runtime instance. You can also use this command to push individual catalina.properties to each tc Runtime instance.

Exit codes: Returns 0 if completely successful. If you execute the command against a single tc Runtime instance, the command returns an exit code of 1 if it failed to push the configuration file. If you execute the command against a group of tc Runtime instances, the command returns 1 for a general blanket failure. If the command fails for some tc Runtime group members but succeeds for others, the command returns an exit code of the number of failures and outputs to stdout one line for each failure, along with the reason.

Table 26. Options of the put-file Command

OptionDescriptionRequired?
--servernameName of the tc Runtime instance to which you want to push a configuration file.

Use list-servers to get the names of the tc Runtime instances in the HQ inventory.

When pushing a configuration file to a single tc Runtime instance, specify --servername or --serverid, but not both.
--serveridID of the tc Runtime instance to which you want to push a configuration file.

Use list-servers to get the IDs of the tc Runtime instances in the HQ inventory.

When pushing a configuration file to a single tc Runtime instance, specify --servername or --serverid, but not both.
--groupnameSpecifies the name of the tc Runtime group to which you want to push a configuration file.

Use list-groups to get the names and IDs of the tc Runtime groups in the HQ inventory.

When pushing a configuration file to a tc Runtime group, specify --groupname or --groupid, but not both.
--groupidSpecifies the ID of the tc Runtime group to which you want to push a configuration file.

Use list-groups to get the names and IDs of the tc Runtime groups in the HQ inventory.

When pushing a configuration file to a tc Runtime group, specify --groupname or --groupid, but not both.
--targetfileName of the configuration file that you want to update. Typical values include conf/server.xml, conf/catalina.properties, conf/web.xml, or conf/context.xml.

Use a forward or backward slash to specify directories; the slashes are resolved on the corresponding computer platform on which the command is eventually run.

Yes.
--fileName of the file, local to the computer on which you are running the tcsadmin script, that you want to push to the tc Runtime instance or group. If you enter a relative pathname, it is local to the working directory of the script, which by default is the top-level installation directory of the script, such as /usr/springsource-tcserver- scripting-client-2.1.X.RELEASE.Yes.
--nobackupfileSpecifies that the tcsadmin script should NOT create a backup of the existing configuration file before the script pushes the new file to the tc Runtime instance. The default behavior if you do not specify this option is for the script to always create a backup of the file.

This option is useful if, for example, you are pushing a file to the webapps directory. If the script were to create a backup copy of the file, the tc Runtime instance would then try to deploy both the backup and the new file.

No.

The example pushes a server.xml configuration file to all members of the tc Runtime group called Group1; the file that is pushed is located on the local computer and is called /tmp/group-server.xml:

prompt$ ./tcsadmin put-file --groupname=Group1 --file=/tmp/group-server.xml --targetfile=conf/server.xml

list-jvm-options

List all the Java virtual machine (JVM) options that are currently set for a single tc Runtime instance.

The command gets the currently set JVM options from the following locations:

  • Unix: The JVM_OPTS variable set in the bin/setenv.sh file.

  • Windows: The wrapper.java.additional.x property in the conf/wrapper.conf file.

The command returns each JVM option on a single line; for example:

prompt> ./tcsadmin list-jvm-options --servername="example_server"
-Xmx512m
-Xms128m
-Xss=192k
-Dmy.custom.prop=foo

Exit codes: Returns 0 if successful and 1 on failure.

Table 27. Options of the list-jvm-options Command

OptionDescriptionRequired?
--servernameName of the tc Runtime instance from which you want to list the currently-set JVM options.

Use list-servers to get the names of the tc Runtime instances in the HQ inventory.

Specify --servername or --serverid, but not both.
--serveridSpecifies the ID of the tc Runtime instance from which you want to list the currently-set JVM options.

Use list-servers to get the IDs of the tc Runtime instances in the HQ inventory.

Specify --servername or --serverid, but not both.

The example gets the JVM options that are currently set for a tc Runtime instance with ID 10045:

prompt$ ./tcsadmin list-jvm-options --serverid=10045 

set-jvm-options

Modify the JVM options for a tc Runtime instance or a group of tc Runtime instances.

The command sets the JVM options by updating the following files on the target tc Runtime instance or instances:

  • Unix: The JVM_OPTS variable in the bin/setenv.sh file.

  • Windows: The wrapper.java.additional.x property in the conf/wrapper.conf file.

Warning: The set-jvm-options command overwrites any existing JVM options; it does not add to existing options. For example, if you have previously set the -Xmx512m and -Xss192k JVM options for the tc Runtime instance, and then you execute the following set-jvm-options command:

prompt$ ./tcsadmin set-jvm-options --options=-Xms384m --serverid=10045

only the -Xms384m JVM option will be set; the -Xss192k option is no longer set.

Exit codes: Returns 0 if completely successful. If you execute the command against a single tc Runtime instance, the command returns an exit code of 1 if it failed to set the JVM options. If you execute the command against a group of tc Runtime instances, the command returns 1 for a general blanket failure. If the command fails for some tc Runtime group members but succeeds for others, it returns an exit code of the number of failures and outputs to stdout one line for each failure, along with the reason.

Table 28. Options of the set-jvm-options Command

OptionDescriptionRequired?
--servernameName of the tc Runtime instance whose JVM options you want to set.

Use list-servers to get the names of the tc Runtime instances in the HQ inventory.

When running this command against a single tc Runtime instance, specify --servername or --serverid, but not both.
--serveridID of the tc Runtime instance whose JVM options you want to set.

Use list-servers to get the IDs of the tc Runtime instances in the HQ inventory.

When running this command against a single tc Runtime instance, specify--servername or --serverid, but not both.
--groupnameName of the tc Runtime group whose JVM options you want to set. Each tc Runtime instance member will be updated.

Use list-groups to get the names and IDs of the tc Runtime groups in the HQ inventory.

When running this command against a tc Runtime group, specify --groupname or --groupid, but not both.
--groupidSpecifies the ID of the tc Runtime group whose JVM options you want to set. Each tc Runtime instance member will be updated.

Use list-groups to get the names and IDs of the tc Runtime groups in the HQ inventory.

When running this command against a tc Runtime group, specify --groupname or --groupid, but not both.
--optionsComma-separated list of JVM options that you want to set.

If an option value itself contains a comma, make sure you escape the comma by preceding it with a backslash (\). For example, the option --options="-Xmx512m, -Dsomeprop=value1\,value2, -Xms128m" resolves into three options: -Xmx512m, -Dsomeprop=value1,value2 and -Xms128m.

To remove all JVM options, use the following syntax: --option="".

Yes.

The example sets the initial Java heap size (using -Xms) and the maximum Java heap size (using -Xmx) for each tc Runtime instance in the group called Group1:

prompt$ ./tcsadmin set-jvm-options --groupname=Group1 --options=-Xms512m,-Xmx1024m