Application Management Commands

This section documents the tcsadmin commands that you use to manage applications deployed to a tc Runtime instance or group. See also General Syntax of the tcsadmin Command-Line Interface.

list-applications

List the applications deployed to a tc Runtime instance or group and get the current status of the applications.

Narrow the scope of the command by specifying a particular service (such as Catalina) or virtual host (such as localhost) of the tc Runtime instance or group. Use the names of the service or virtual host in the corresponding server.xml configuration file of the tc Runtime instance.

The list-applications command returns the following information for each deployed application, with each bit of information separated by the | character:

  • Name of the service of the tc Runtime instance to which the application is deployed. This name corresponds to the service name in the server.xml file for the tc Runtime instance.

  • Name of the virtual host of the tc Runtime instance to which the application is deployed. This name corresponds to the host name in the server.xml file for the tc Runtime instance.

  • Name (context) of the deployed application.

  • Version of the deployed application.

  • Status of the application: Running or Stopped. If you are listing the deployed applications of a group of tc Runtime instances and the application is started on some tc Runtime instances and stopped on other instances, the status message is Mixed.

  • Number of current active sessions for the application.

Exit codes: Returns 0 if it is 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 retrieve the information for the deployed applications. 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 only some of the tc Runtime members of the group but succeeds for others, then 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 19. Options of the list-applications Command

OptionDescriptionRequired?
--servernameName of the tc Runtime instance for which you want to list the deployed applications.

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

When listing the applications deployed to a single tc Runtime instance, specify --servername or --serverid, but not both.
--serveridID of the tc Runtime instance for which you want to list the deployed applications.

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

When listing the applications deployed to a single tc Runtime instance, specify --servername or --serverid, but not both.
--groupnameName of the tc Runtime group for which you want to list the deployed applications. This option lists applications on each tc Runtime member of the group, even if the application is not consistently deployed to each member of the group.

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

When listing the applications deployed to a tc Runtime group, specify --groupname or --groupid, but not both.
--groupidID of the tc Runtime group for which you want to list the deployed applications. This option lists applications on each tc Runtime member of the group, even if the application is not consistently deployed to each member of the group.

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

When listing the applications deployed to a tc Runtime group, specify --groupname or --groupid, but not both.
--tcserviceName of the service of the tc Runtime instance for which you want to list the deployed applications. By default, tc Runtime instances are configured with the Catalina service.

To get the names of the services of a tc Runtime instance, invoke the HQ user interface in a browser, navigate to the tc Runtime instance, and go to the Views > Server Configuration > Services tab, which lists the configured services. Or, in the tc Runtime instance's server.xml configuration file, look for <Service> elements.

If you do not specify this option, list-applications lists the applications in all services of the specified tc Runtime instance or group.

No.
--tchostName of the virtual host of the tc Runtime instance for which you want to list the deployed applications. By default, tc Runtime instances are configured with the localhost virtual host.

To get the names of the virtual hosts of a tc Runtime instance, invoke the HQ user interface in a browser, navigate to the tc Runtime instance, and go to the Views > Server Configuration > Services tab, click on a service in the table, and then click on the Hosts link in the left. Or, in the tc Runtime instance's server.xml configuration file, look for <Host> elements.

If you do not specify this option, the list-applications command lists the applications in all virtual hosts of the specified tc Runtime instance or group.

No.
--applicationName of a Web application for which you want status information.No.

This example lists the Web applications deployed to the a tc Runtime instance with name example_server, along with sample output. The command limits the scope of the list to the applications deployed to the Catalina service and localhost virtual host.

prompt$ ./tcsadmin list-applications --servername="example_server" --tcservice=Catalina --tchost=localhost

Catalina|localhost|ROOT|Running|0
Catalina|localhost|insight|Running|0

The next example shows how to list the Web applications deployed to all members of the Group1 tc Runtime group. The output includes the applications that are deployed to all members of the group and applications deployed only to a single member of the group.

prompt$ ./tcsadmin list-applications --groupname=Group1

This example shows how to view the status of a specific Web application deployed to a single tc Runtime instance named example_server. If the application is not currently deployed to the server, you get an error.

prompt$ ./tcsadmin list-applications --application=swf-booking-mvc --servername="example_server"

deploy-application

Upload and deploy a Web application WAR file to a tc Runtime instance or group.

The WAR file can reside on the same computer on which you are running the tcsadmin command-line interface or on the remote computer on which the tc Runtime instance is running.

If you use this command to deploy a Web application to a group of tc Runtime instances and you specify a remote path for the WAR file, then it is assumed that the WAR file is located on every computer that hosts the members of the tc Runtime group and that the WAR file's directory pathname is identical on each computer. A good way to implement this is to mount a shared network drive on each computer that hosts a tc Runtime instance, then put the WAR file on the shared drive. Make sure that the name of the mounted shared drive is the same on each computer.

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 deploy the application. 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 only some of the tc Runtime members of the group but succeeds for others, then 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 20. Options of the deploy-application Command

OptionDescriptionRequired?
--servernameName of the tc Runtime instance to which you will deploy the Web application.

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

When deploying to a single tc Runtime instance, specify either --servername or --serverid, but not both.
--serveridID of the tc Runtime instance to which you will deploy the Web applications.

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

When deploying to a single tc Runtime instance, specify either --servername or --serverid, but not both.
--groupnameName of the tc Runtime group to which you will deploy the Web application. This option deploys the application to each member of the group.

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

When deploying an application to a tc Runtime group, specify either --groupname or --groupid, but not both.
--groupidID of the tc Runtime group to which you want to deploy the Web application. This option deploys the application to every single member of the group.

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

When deploying an application to a tc Runtime group, specify either --groupname or --groupid, but not both.
--tcserviceName of the service of the tc Runtime instance or group to which the Web application will be deployed. Default is Catalina.

To get the names of the services of a tc Runtime instance or group, invoke the HQ user interface in a browser, navigate to the tc Runtime instance, and go to the Views > Server Configuration > Services tab which lists the configured services. Or, in the tc Runtime instance's server.xml configuration file, look for <Service> elements.

No.
--tchostName of the virtual host of the tc Runtime instance or group to which the Web application will be deployed. Default value is localhost.

To get the names of the virtual hosts of a tc Runtime instance or group, invoke the HQ user interface in a browser, navigate to the tc Runtime instance, and go to the Views > Server Configuration > Services tab, click on a service in the table, and then click on the Hosts link in the left. Or, in the tc Runtime instance's server.xml configuration file, look for <Host> elements.

No.
--localpathFull pathname of the Web application WAR file, local to the computer on which you are running the tcsadmin command-line interface.Specify either --localpath or --remotepath but not both.
--remotepathFull pathname of the Web application WAR file on the remote computer that hosts the tc Runtime instances (either single or members of a group.) If you are deploying the Web application to a group, it is assumed that the WAR file exists on each computer that hosts the members of the group and that the full pathname of the files is identical. You can put the WAR file on a shared network drive as long as the drive is mounted with the same name on each computer that hosts the tc Runtime instances.Specify either --localpath or --remotepath but not both.
--contextpathContext path of the Web application. The context path refers to the pathname used in the URL to invoke the Web application, relative to the tc Runtime instance's root URL.

The default value of this option is the name of the WAR file without any file endings or pathnames. For example, if you deploy the local file /home/myapps/myStore.war then the default context path is myStore.

No.

The following example shows how to deploy an application whose WAR file is called /home/myapps/swf-booking-mvc.war and is located on the same computer on which you are running the tcsadmin command-line interface. The command deploys the application to all members of the tc Runtime group called Group1. Because no --contextpath option is specified, the context path used to invoke the deployed application will be swf-booking-mvc; the full URL will be something like http://myhost:8080/swf-booking-mvc.

prompt$ deploy-application --groupname=Group1 --localpath=/tmp/swf-booking-mvc.war 

start-application

Start an application that is currently deployed to a tc Runtime instance or group.

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 start the application. 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 members of the group 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.

The following table lists the options you can specify with this command.

Table 21. Options of the start-application Command

OptionDescriptionRequired?
--servernameName of the tc Runtime instance on which the Web application you want to start is deployed.

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

When starting an application deployed to a single tc Runtime instance, specify --servername or --serverid, but not both.
--serveridID of the tc Runtime instance on which the Web application you want to start is deployed.

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

When starting an application deployed to a single tc Runtime instance, specify --servername or --serverid, but not both.
--groupnameName of the tc Runtime group on which the application you want to start is deployed.

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

When starting an application deployed to a tc Runtime group, specify --groupname or --groupid, but not both.
--groupidID of the tc Runtime group on which the application you want to start is deployed.

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

When starting an application deployed to a tc Runtime group, specify --groupname or --groupid, but not both.
--tcserviceName of the service of the tc Runtime instance or group where the application you want to start is deployed. Default value is Catalina.

To get the names of the services of a tc Runtime instance or group, invoke the HQ user interface in a browser, navigate to the tc Runtime instance, and go to the Views > Server Configuration > Services tab, which lists the configured services. Or, in the tc Runtime instance's server.xml configuration file, look for <Service> elements.

No.
--tchostName of the virtual host of the tc Runtime instance or group where the application you want to start is deployed. Default value is localhost.

To get the names of the virtual hosts of a tc Runtime instance or group, invoke the HQ user interface in a browser, navigate to the tc Runtime instance, go to the Views > Server Configuration > Services tab, click on a service in the table, and then click on the Hosts link in the left. Or, in the tc Runtime instance's server.xml configuration file, look for <Host> elements.

No.
--applicationName of the Web application you want to start. It is assumed that the application has been previously deployed.

If you do not specify this option, then tcsadmin starts all relevant applications, depending on the other options you have specified.

Use list-applications to get the list of applications deployed to a tc Runtime instance or group.

No.
--revisionSpecifies the particular revision of the application to start. This feature, available only on instances using Tomcat 7, allows you to deploy a new revision without interrupting the current version of the application. Existing user sessions continue using the current application version, but new sessions use the highest numbered revision that has been deployed.No.

The example starts an application called swf-booking-mvc deployed to the tc Runtime group called Group1:

prompt$ ./tcsadmin start-application --groupname=Group1 --application=swf-booking-mvc 

stop-application

Stop an application that is currently deployed to a tc Runtime instance or group.

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 stop the application. If you execute against a group of tc Runtime instances, the command returns 1 for a general blanket failure; if the command fails for only some of the tc Runtime members of the group 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 22. Options of the stop-application Command

OptionDescriptionRequired?
--servernameName of the tc Runtime instance on which the Web application you want to stop is deployed.

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

When stopping an application deployed to a single tc Runtime instance, specify --servername or --serverid, but not both.
--serveridID of the tc Runtime instance on which the Web application you want to stop is deployed.

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

When stopping an application deployed to just a single tc Runtime instance, specify --servername or --serverid, but not both.
--groupnameName of the tc Runtime group on which the application you want to stop is deployed.

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

When stopping an application deployed to a tc Runtime group, specify --groupname or --groupid, but not both.
--groupidID of the tc Runtime group on which the application you want to stop is deployed.

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

When stopping an application deployed to a tc Runtime group, specify --groupname or --groupid, but not both.
--tcserviceName of the service of the tc Runtime instance or group where the application you want to stop is deployed. Default is Catalina.

To get the names of the services of a tc Runtime instance or group, invoke the HQ user interface in a browser, navigate to the tc Runtime instance, and go to the Views > Server Configuration > Services tab, which lists the configured services. Or, in the tc Runtime instance's server.xml configuration file, look for <Service> elements.

No.
--tchostName of the virtual host of the tc Runtime instance or group where the application you want to stop is deployed. Default is localhost.

To get the names of the virtual hosts of a tc Runtime instance or group, invoke the HQ user interface in a browser, navigate to the tc Runtime instance, go to the Views > Server Configuration > Services tab, click on a service in the table, and then click on the Hosts link in the left. Or, in the tc Runtime instance's server.xml configuration file, look for <Host> elements.

No.
--applicationName of the Web application you want to stop. It is assumed that the application has been previously deployed.

If you do not specify this option, tcsadmin stops all relevant applications, depending on the other options you have specified.

Use list-applications to get the list of applications deployed to a tc Runtime instance or group.

No.
--revisionSpecifies the particular version of the application to stop. This feature is available only on instances using Tomcat 7. You can use the stop-application command with this option to stop an older version of the application after deploying the new version and ensuring that all sessions using the older version have ended.No.

The example stops an application called swf-booking-mvc deployed to the tc Runtime group called Group1:

prompt$ ./tcsadmin stop-application --groupname=Group1 --application=swf-booking-mvc 

reload-application

Reload an application that is currently deployed to a tc Runtime instance or group.

Reloading refers to tc Runtime re-reading the WAR file into memory. Use this command if you have updated the original WAR file.

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 reload the application. If you execute the command against a group of tc Runtime instances, it 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.

You can execute the reload-application command on both started and stopped Web applications.

Table 23. Options of the reload-application Command

OptionDescriptionRequired?
--servernameName of the tc Runtime instance on which the Web application you want to reload is deployed.

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

When reloading an application deployed to just a single tc Runtime instance, you must specify either --servername or --serverid, but not both.
--serveridID of the tc Runtime instance on which the Web application you want to reload is deployed.

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

When reloading an application deployed to just a single tc Runtime instance, you must specify either --servername or --serverid, but not both.
--groupnameName of the tc Runtime group on which the application you want to reload is deployed.

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

When reloading an application deployed to a tc Runtime group, you must specify either --groupname or --groupid, but not both.
--groupidID of the tc Runtime group on which the application you want to reload is deployed.

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

When reloading an application deployed to a tc Runtime group, you must specify either --groupname or --groupid, but not both.
--tcserviceName of the service of the tc Runtime instance or group where the application you want to reload is deployed. Default is Catalina.

To get the names of the services of a tc Runtime instance or group, invoke the HQ user interface in a browser, navigate to the tc Runtime instance, and go to the Views > Server Configuration > Services tab, which lists the configured services. Or, in the tc Runtime instance's server.xml configuration file, look for <Service> elements.

No.
--tchostName of the virtual host of the tc Runtime instance or group where the application you want to reload is deployed. Default value is localhost.

To get the names of the virtual hosts of a tc Runtime instance or group, invoke the HQ user interface in a browser, navigate to the tc Runtime instance, go to the Views > Server Configuration > Services tab, click on a service in the table, and then click on the Hosts link in the left. Or, in the tc Runtime instance's server.xml configuration file, look for <Host> elements.

No.
--applicationName of the Web application you want to reload. It is assumed that the application has been previously deployed.

If you do not specify this option, tcsadmin reloads all relevant applications, depending on the other options you have specified.

Use list-applications to get the list of applications deployed to a tc Runtime instance or group.

No.
--revisionSpecifies the particular version of the application to reload. This feature is available only on instances using Tomcat 7.No.

The example reloads an application called swf-booking-mvc deployed to the tc Runtime group called Group1:

prompt$ ./tcsadmin reload-application --groupname=Group1 --application=swf-booking-mvc 

undeploy-application

Undeploy an application that is currently deployed to a tc Runtime instance or group.

When you undeploy an application, you essentially obliterate it from the tc Runtime environment. The only way to use the application again is by deploying it from scratch.

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 undeploy the application. If you execute the command against a group of tc Runtime instances, the command returns 1 for a general blanket failure. If it fails for some tc Runtime members of the group 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 24. Options of the undeploy-application Command

OptionDescriptionRequired?
--servernameName of the tc Runtime instance on which the Web application you want to undeploy is currently deployed.

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

When undeploying an application deployed to just a single tc Runtime instance, you must specify either --servername or --serverid, but not both.
--serveridID of the tc Runtime instance on which the Web application you want to undeploy is currently deployed.

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

When undeploying an application deployed to just a single tc Runtime instance, you must specify either --servername or --serverid, but not both.
--groupnameName of the tc Runtime group on which the application you want to undeploy is deployed.

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

When undeploying an application deployed to a tc Runtime group, specify --groupname or --groupid, but not both.
--groupidID of the tc Runtime group on which the application you want to undeploy is deployed.

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

When undeploying an application deployed to a tc Runtime group, specify --groupname or --groupid, but not both.
--tcserviceName of the service of the tc Runtime instance or group where the application you want to undeploy is deployed. Default is Catalina.

To get the names of the services of a tc Runtime instance or group, invoke the HQ user interface in a browser, navigate to the tc Runtime instance, and go to the Views > Server Configuration > Services tab, which lists the configured services. Or, in the tc Runtime instance's server.xml configuration file, look for <Service> elements.

No.
--tchostName of the virtual host of the tc Runtime instance or group where the application you want to undeploy is deployed. Default is localhost.

To get the names of the virtual hosts of a tc Runtime instance or group, invoke the HQ user interface in a browser, navigate to the tc Runtime instance, go to the Views > Server Configuration > Services tab, click on a service in the table, and then click on the Hosts link in the left. Or, in the tc Runtime instance's server.xml configuration file, look for <Host> elements.

No.
--applicationName of the Web application you want to undeploy. It is assumed that the application has been previously deployed.

If you do not specify this option, tcsadmin undeploys all relevant applications, depending on the other options you have specified.

Use list-applications to get the list of applications deployed to a tc Runtime instance or group.

No.
--revisionSpecifies the particular version of the application to undeploy. This feature is available only on instances using Tomcat 7. You can use the undeploy-application command with this option to undeploy an older version of the application after deploying the new version and ensuring that all sessions using the older version have ended.No.

The example undeploys an application called swf-booking-mvc currently deployed to the tc Runtime group called Group1:

prompt$ ./tcsadmin undeploy-application --groupname=Group1 --application=swf-booking-mvc