Inventory Commands

This section documents the tcsadmin commands that you use to manage the HQ inventory. 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.

list-servers

List all servers in the HQ inventory of type SpringSource tc Runtime 6.0 and SpringSource tc Runtime 7.0.

The command outputs the following information for each tc Runtime instance, with each bit of information separated by a | character:

  • The internal HQ ID of the tc Runtime instance. This ID is guaranteed to be unique across all resources in the HQ inventory. You can use this ID as a parameter value for other tcsadmin commands, such as remove-server-from-group, to uniquely identify a specific tc Runtime instance.

  • The name of the tc Runtime instance.

  • The description of the tc Runtime instance.

  • The status of the tc Runtime instance, such as Stopped or Running.

Exit codes: Returns 0 if successful and 1 on failure to retrieve tc Runtime information.

Table 13. Options of the list-servers Command

OptionDescriptionRequired?
--platformnameParticular platform for which you want the associated list of tc Runtime instances. If you do not specify this option, then the command returns all tc Runtime instances in the entire HQ inventory.

To get the exact name of an HQ platform, invoke the HQ user interface in your browser, click the Resources > Browse link at the top, then click the Platforms (X) link; the platform names in the HQ inventory appear in the Platform column of the table.

No.
--groupnameName of a tc Runtime Compatible Group/Cluster whose list of member tc Runtime instances you want to view. If you do not specify this option, then the command returns all tc Runtime instances associated with the specified platform or in the entire HQ inventory.

To get the exact name of a tc Runtime group, see list-groups.

No.

This example uses list-servers to list all tc Runtime instances in the HQ inventory and shows sample output:

prompt$ ./tcsadmin.sh list-servers

10115|mydesktop tc Runtime myserver|/opt/vmware/vfabric-tc-server-standard/myserver|Running

This example lists the tc Runtime instances that are part of the group called Group1:

prompt$ ./tcsadmin.sh list-servers --groupname=Group1

modify-server

Change the name or description of a tc Runtime instance.

Exit codes: Returns 0 on success and 1 on failure to change the name or description of a tc Runtime instance.

Table 14. Options of the modify-server Command

OptionDescriptionRequired?
--serveridID of the tc Runtime instance that you want to modify.

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

Yes.
--nameNew name of the tc Runtime instance.No.
--descriptionNew description of the tc Runtime instance.No.

This example changes the name and description of a tc Runtime instance with id 10007:

prompt$ ./tcsadmin.sh modify-server --serverid=10007 --name="tc Runtime 1-XX" \
       --description="First tc Runtime running on XX computer" 

Enter the command on one line; the example shows it on two lines for clarity.

list-groups

List all tc Runtime groups in the HQ inventory.

The groups are of type Compatible Group/Cluster that contain servers of type SpringSource tc Runtime 6.0 and SpringSource tc Runtime 7.0.

The command outputs the following information for each tc Runtime group, with each bit of information separated by the | character:

  • Internal HQ ID of the tc Runtime group. This ID is guaranteed to be unique across all resources in the HQ inventory.

  • Name of the tc Runtime group.

  • Description of the tc Runtime group.

  • Location of the tc Runtime group.

Exit codes: Returns 0 on success and 1 on failure.

This command does not have any associated options.

This example lists all known tc Runtime groups, along with sample output:

prompt$ ./tcsadmin.sh list-groups

10001|tcs-group|A group of tc Runtime instances|San Francisco
10002|my-group|Another group of tc Runtime instances|Oakland

create-group

Create a Compatible Group/Cluster with resources of type SpringSource tc Runtime 6.0 or SpringSource tc Runtime 7.0.

The create-group command creates an empty group; use add-server-to-group to add specific tc Runtime instances to the group.

Exit codes: Returns 0 on success and 1 on failure to create the group.

Table 15. Options of the list-groups Command

OptionDescriptionRequired?
--nameName of the tc Runtime group you want to create.Yes.
--descriptionDescription of the new group.No.
--locationPhysical location of the group's hardware. The location is for your own accounting purposes; it does not specify internal technical information for the HQ Server.No.
--versionAllows only tc Runtime instances of the specified version to be added to the group.No.

This example creates a new empty group of tc Runtime instances with the specified name, description, version, and location:

prompt$ ./tcsadmin.sh create-group --name=Group2 --description="A group of tc Runtime 7.0 instances" \
    --version=7.0 --location="Austin" 

add-server-to-group

Add a tc Runtime instance to an existing tc Runtime group. The tc Runtime version must be compatible with the group version.

Exit codes: The command returns 0 on success and 1 on failure to add the tc Runtime instance to the group.

Table 16. Options of the add-server-to-group Command

OptionDescriptionRequired?
--groupnameName of the group to which you will add a new tc Runtime instance.

Use list-groups to view the list of existing tc Runtime groups.

Yes.
--servernameName of the tc Runtime instance you will add to the group.

To get a list of tc Runtime instance names in the HQ inventory, use list-servers.

Specify --servername or --serverid, but not both.
--serveridID of the tc Runtime instance you will add to the group.

To get a list of the tc Runtime instance names and IDs in the HQ inventory, use list-servers.

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

This example adds the tc Runtime instance with name example_server to the existing tc Runtime group called Group1:

prompt$ ./tcsadmin.sh add-server-to-group --groupname=Group1 --servername="example_server" 

remove-server-from-group

Remove a tc Runtime instance from an existing group.

Exit codes: Returns 0 if successful and 1 on failure to remove a server from the group.

Table 17. Options of the remove-server-from-group Command

OptionDescriptionRequired?
--groupnameName of the group from which you will remove an existing tc Runtime instance member.

Use list-groups to view the list of existing tc Runtime groups.

Yes.
--servernameName of the tc Runtime instance you will remove from the group.

Use list-servers to view the tc Runtime instance names and IDs in the HQ inventory.

Specify --servername or --serverid, but not both.
--serveridID of the tc Runtime instance you will remove from the group.

Use list-servers to view the tc Runtime instance names and IDs in the HQ inventory.

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

This example removes the tc Runtime instance with name example_server from the existing tc Runtime group called Group1:

prompt$ ./tcsadmin.sh remove-server-from-group --groupname=Group1 --servername="example_server" 

delete-group

Delete an existing tc Runtime group. Deleting a group does not delete the tc Runtime instances that make up the group.

Exit codes: Returns 0 on success and 1 on failure to delete the group.

Table 18. Options of the delete-group Command

OptionDescriptionRequired?
--nameName of the tc Runtime group that you want to delete.

Use list-groups to view the list of existing tc Runtime groups.

Yes.

This example deletes an existing tc Runtime group:

prompt$ ./tcsadmin.sh delete-group --name="Group1"