LATEST VERSION: 4.0 - CHANGELOG
Pivotal tc Server v4.0

tcserver Command Reference

New in tc Server 4.0 the tcruntime-ctl, tcruntime-admin, and tcruntime-instance scripts have been replaced with a single script called tcserver. This script improves upon functionality previously provided by tcruntime-ctl and tcruntime-instance scripts.

Introduction

The commands are broken into 3 categories

  • Instance Lifecycle Commands. These are also known as control commands previously provided by tcruntime-ctl scripts.
  • Instance Provisioning Commands. These commands allow for the creation and manipulation of instances previously provided by tcruntime-instance.
  • Administrative Tooling. These commands provide administrative functions previously provided by tcruntime-admin scripts.

Requirements

This command launches a JVM which requires Java 1.6 or newer. As such a JDK/JRE needs to be installed on the local system. This command uses the JAVA_HOME environment variable, however, if that is not specified then it will attempt to local a suitable JRE/JDK and internally set the environment variable.

Configuration

The tcserver command has the ability to read from a configuration properties file and use those properties as default values.

More information on this configuration properties is found in the tcserver.properties reference documentation.

Commands

Table 1. tcserver Instance Provisioning Commands
Command Description
apply-template Applies a template to an existing instance
create Creates a new tc Server instance.
create-from-file Creates a new tc Server instance from an instance descriptor file.
list List existing instances and their details
modify-version Modify the version of Tomcat that an instance runs with
upgrade Upgrade an instance created with a previous version
Table 2. tcserver Instnce Lifecycle Commands
Command Description
restart Restarts a running tc Runtime instance
run Run an instance as a foreground process
start Start an instance as a daemon process
status Reports the status of an instance
stop Stops a running tc Runtime instance
verbose-status Reports the status of an instance
Table 3. tcserver Administrative tooling Commands
Command Description
decode Decodes strings encoded using the ‘encode’ command
encode Encodes strings for use in property values
get-runtime Installs tc Runtimes from the tc Server Runtime Repository
get-template Installs a template
list-runtimes Lists available tc Runtimes
list-templates Lists available templates from tc Server template repository
support-bundle Create a zip archive of common files needed for diagnostics
thread-dump Log a thread dump to log file
Table 4. tcserver General Commands
Command Description
help Displays help information on a command
version Shows either the version of tc Runtime and instance is using or version of the tcserver command.

Command Reference

apply-template

This command applies a template to an existing instance.

Usage:

tcserver apply-template [OPTIONS] <instance-name>

Where <instance-name> is the name of the instance.

Use the apply-template command to apply a new template to an existing tc Runtime instance.

Refer to the README.txt file in the instance directory for the list of templates that have already been applied to the instance. For a list and description of all templates, see Templates Provided by tc Runtime.

By default, you cannot apply the same template twice to an instance. However, there are two options which allows you to apply the same template more than once.

  1. The --override-duplicate-template option. This option overwrites the previous template.
  2. You can specify the template with a special name. This will apply the template using the special name. The special name is specified by appending the @ sign and the name after the template name.

Example:

tcserver apply-template demo-instance -t nio@secondary-ports

The above will apply the bio template however instead of generating properties such as nio.http.port the properties will be named nio@secondory-ports.http.port which allows the second connector to use different ports.

Table 5. apply-template options
Option Description
-e, –template-directory <directory> Specifies the directory in which the template is stored. This should point to the parent directory of the template and not the template itself.
-f, –properties-file <file> Specifies the file which contains properties used by the template. This option may be specified multiple times. A property defined with the –property option takes precedence.
-i, –instance-directory Specifies the directory which contains the instance. The default directory is the current directory. This references the parent directory of the instance.
–ignore-missing-property-placeholders Ignores the forcing replacement of any property placeholders without a value and leaves them as placeholders.
–interactive Runs interactively, prompting the user for configuration.
–override-duplicate-template Overrides the limitation on duplicate being used.
–p, –property <template.key=value> Specifies a configuration property. Maybe be used multiple times. The template name should be used as a prefix for the key. For example to specify the http.port property for the nio template “nio.http.port” would be used for the key.
-t, –template <template Specifies the name of the template to use

create

This command creates a new instance.

Usage:

tcserver create [OPTIONS] <instance-name>

The create command accepts a number of options for customizing the instance.

When you create a new instance, and you do not specify the --template option to apply one or more specific templates, the tcserver script creates a basic tc Runtime instance that uses the default template (called nio); this template adds the Non-blocking IO (NIO) HTTP Connector to the server.xml of the instance. To configure different or additional features using the templates, such as the BIO Connector, clustering, or SSL, use the --template option to specify the appropriate template; you must use the option for each template you want to apply.

Starting in tc Server 4.0.0.RELEASE a new default instances-directory is used. Previously the current directory was used if --instances-directory or -i were omitted from the command line.

The following table lists options for the create command of tcserver. When specifying the most common options, you can use either the short form (such as -i) or the long form (such as --instance-directory); less common options support only the long form.

Table 6. create options
Option Description
-e, –templates-directory <directory> Specifies the directory in which the template is stored. This should point to the parent directory of the template and not the template itself.
-f, –properties-file <file> Specifies the file which contains properties used by the template. This option may be specified multiple times. A property defined with the –property option takes precedence.
–force Forces creation of the instance even if it already exists.
-i, –instances-directory Specifies the directory which contains the instance. The default directory is the current directory. This references the parent directory of the instance.
–interactive Runs interactively, prompting the user for configuration.
–java-home <directory> Specifies the JAVA_HOME to be used at runtime by the instance.
–layout <layout-type> Specifies the type of layout to use. Must be either “combined” or “separate” which is the default. The “separate” layout uses a separate CATALINA_BASE and CATALINA_HOME and allows for easier upgrades. The “combined” layout uses Tomcat’s default layout.
–p, –property <template.key=value> Specifies a configuration property. Maybe be used multiple times. The template name should be used as a prefix for the key. For example to specify the http.port property for the nio template “nio.http.port” would be used for the key.
-r, –runtimes-directory <directory> Specifies the directory in which to look for tc Runtimes.
-t, –template <template> Specifies the name of the template to use
-v, –version <version> Specifies the version of tc Runtime to be used by the instance. Omitting this option causes the instance to use the latest available version.

create-from-file

This command creates a new instance.

Usage:

tcserver create-from-file [OPTIONS] <file>

The create-from-file reads the properties file <file> for customizing the instance.

When you create a new instance, and you do not specify the --template option to apply one or more specific templates, the tcserver script creates a basic tc Runtime instance that uses the default template (called nio); this template adds the Non-blocking IO (NIO) HTTP Connector to the server.xml of the instance. To configure different or additional features using the templates, such as the BIO Connector, clustering, or SSL, use the --template option to specify the appropriate template; you must use the option for each template you want to apply.

Starting in tc Server 4.0.0.RELEASE a new default instances-directory is used. Previously the current directory was used if --instances-directory or -i were omitted from the command line.

The following table lists options for the create command of tcserver. When specifying the most common options, you can use either the short form (such as -i) or the long form (such as --instance-directory); less common options support only the long form.

Table 7. Create-from-file properties
Option Description
instance-name The name of the instance
templates-directory Specifies the directory in which the template is stored. This should point to the parent directory of the template and not the template itself.
properties-file.[0-99] Specifies the file which contains properties used by the template. This property may be specified multiple times each time with a unique number. A property defined with the –property option takes precedence.
force Forces creation of the instance even if it already exists.
instances-directory Specifies the directory which contains the instance. The default directory is the current directory. This references the parent directory of the instance.
interactive Runs interactively, prompting the user for configuration.
java-home Specifies the JAVA_HOME to be used at runtime by the instance.
layout Specifies the type of layout to use. Must be either “combined” or “separate” which is the default. The “separate” layout uses a separate CATALINA_BASE and CATALINA_HOME and allows for easier upgrades. The “combined” layout uses Tomcat’s default layout.
property.[0-99] Specifies a configuration property. Each usage should have a unique number. The template name should be used as a prefix for the key. For example to specify the http.port property for the nio template “nio.http.port.00” would be used for the key.
runtimes-directory Specifies the directory in which to look for tc Runtimes.
template.[0-99] Specifies the name of the template to use. Each usage should have a unique number.
version Specifies the version of tc Runtime to be used by the instance. Omitting this option causes the instance to use the latest available version.

list

This command lists instances.

Usage:

tcserver list [OPTIONS] <instance-name>

Where <instance-name> is the name of the instance.

Table 7. list options
Option Description
-i, –instance-directory Specifies the directory which contains the instance. The default directory is the current directory. This references the parent directory of the instance.
-v, –verbose Provides more details about the instances in the list.

modify-version

This command modifies the version of tc Runtime and tc Server scripts used by an instance.

Usage:

tcserver modify-version [OPTIONS] <instance-name>

Where <instance-name> is the name of the instance.

Use the modify-version command to modify the version of tc Runtime used by an existing instance that is pinned to a particular version of tc Runtime.

You cannot use this command to modify an instance so it uses a different major release of tc Runtime, or in other words, from tc Runtime version 7.0.X to 8.0.X. You can use it only to modify the version within a certain major release, such as 7.0.47.A to 7.0.50.A.

Use the --version option to specify the new version of the instance. If you do not specify --version, the resulting instance is pinned to the latest available version of tc Runtime. See Pinning tc Runtime Instances to a Version.

Note: It is assumed that you have already installed the tc Runtime version for which you want to modify the existing instance.

Examples of modifying existing tc Runtime instances are shown after the options reference table.

Table 8. modify-version options
Option Description
-i, –instances-directory Specifies the directory which contains the instance. The default directory is the current directory. This references the parent directory of the instance.
-r, –runtimes-directory <directory> Specifies the directory in which to look for tc Runtimes.
-v, –version <version> Specifies the version of tc Runtime to be used by the instance. Omitting this option causes the instance to use the latest available version.

upgrade

This command upgrades the version of tc Runtime an instance uses

Usage:

tcserver upgrade [OPTIONS] <instance-name>

Where <instance-name> is the name of the instance.

Use the upgrade command to upgrade an instance to a new version of tc Server. The upgrade command copies the existing instance to a new instance directory and updates the files and descriptors in the instance.

Note: This command can not upgrade a tc Runtime instance to a different major version.

The difference between the upgrade command and the modify-version command is that the upgrade command upgrades the tc Server scripts and other tc Server files to a newer version, and the modify-version command changes the tc Runtime version to a tc Runtime based on a different Apache Tomcat release.

The usual procedure for using the upgrade command is to:

  1. Install the new tc Server release in a directory alongside the existing tc Server installation.
  2. Execute the upgrade command from the new tc Server installation directory, specifying the instance to be upgraded in the old tc Server instance directory.

This results in a new tc Runtime instance in the new tc Server installation directory. When all instances have been upgraded, restarted, and verified, the old tc Server instance directory can be removed.

Before you use the upgrade command:

  • If the instance to be upgraded is running, stop it. For example, execute the following command in the tc Server Installation directory:

    tcserver stop demo-instance
    
  • If the instance to be upgraded is installed as a Windows service, uninstall it. For example:

    tcserver uninstall demo-instance
    

After running the upgrade command, install the new instance as a Windows service (if on Windows) and then start the new instance.

Table 9. upgrade options
Option Description
-i, –instances-directory Specifies the directory which contains the instance. The default directory is the current directory. This references the parent directory of the instance.
-r, –runtimes-directory <directory> Specifies the directory in which to look for tc Runtimes.
-v, –version <version> Specifies the version of tc Runtime to be used by the instance. Omitting this option causes the instance to use the latest available version.

restart

This command restarts a running instance.

Usage:

tcserver restart [OPTIONS] <instance-name>

Where <instance-name> is the name of the instance.

Table 10. restart options
Option Description
-i, –instances-directory Specifies the directory which contains the instance. The default directory is the current directory. This references the parent directory of the instance.
–timeout <timeout> Time in seconds to wait for graceful stop before forced termination

run

This command runs and instance in the foreground.

Usage:

tcserver run <instance-name>

Where <instance-name> is the name of the instance.

Table 11. run options
Option Description
-i, –instances-directory Specifies the directory which contains the instance. The default directory is the current directory. This references the parent directory of the instance.

start

This command starts and instance as a daemon or system service.

Usage:

tcserver start <instance-name>

Where <instance-name> is the name of the instance.

Table 12. start options
Option Description
-i, –instances-directory Specifies the directory which contains the instance. The default directory is the current directory. This references the parent directory of the instance.

status

This command displays the status of an instance.

Usage:

tcserver status <instance-name>

Where <instance-name> is the name of the instance.

Table 13. status options
Option Description
-i, –instances-directory Specifies the directory which contains the instance. The default directory is the current directory. This references the parent directory of the instance.

stop

This command stops a running instance.

Usage:

tcserver stop [OPTIONS] <instance-name>

Where <instance-name> is the name of the instance.

Table 14. stop options
Option Description
-i, –instances-directory Specifies the directory which contains the instance. The default directory is the current directory. This references the parent directory of the instance.
–timeout <timeout> Time in seconds to wait for graceful stop before forced termination

verbose-status

This command displays the a more detailed status of an instance.

Usage:

tcserver verbose-status <instance-name>

Where <instance-name> is the name of the instance.

Table 15. verbose-status options
Option Description
-i, –instances-directory Specifies the directory which contains the instance. The default directory is the current directory. This references the parent directory of the instance.

decode

This command decodes an encoded string.

Usage:

tcserver decode <value> <passphrase>

encode

This command encodes a string for use with obfuscation of protected values in instance catalina.properties.

Usage:

tcserver encode <value> <passphrase>

Where <value> is the desired string which should be encoded using <passphrase>. When specifying non-alphanumeric characters it may be required to escape the characters. For example to use the $ in a passphrase you would prepend a \ to the $ such as

tcserver encode mysecret foo\$bar 

get-runtime

This command retrieves a runtime from the tc Server Runtime Repository

Table 16. get-runtime options
Option Description
-r, –runtimes-directory <directory> Specifies the directory in which to install the tc Runtimes.

get-template

This command installs a template. By default if only a name is provided then the template is assumed to be located in the tc Server Template Repository and an attempt is made to download it.

The .zip archive should contain a root directory with the name of the template which follows the standard tc Server template layout.

Usage:

tcserver get-template <template>|<template-url>|<template-directory>|<template-zip-file> [OPTIONS]

The following lists the meaning of the arguments. Only one argument is accepted on the command line.

  • <template> - Name of template in the tc Server Template Repository
  • <template-url> - URL of a .zip file which contains the template. If the URL uses HTTP BASIC AUTH then the –username and –password options should be used.
  • <template-directory> - Local extracted directory of a template
  • <template-zip-file> - Local .zip archive of a template

Note: If using a SSL secured URL (url starting with HTTPS://) it may be necessary to add the remote server’s certificate to the keystone. This should only be required if the remote server is using a certificate signed by an authority that isn’t trusted.

Table 17. get-template options
Option Description
-e, –templates-directory <directory> Specifies the directory in which the template is stored. This should point to the parent directory of the template and not the template itself.
–overwrite Overwrite template directory if it already exists.
-p, –password <password> Password to use when a URL is provided and HTTP BASIC AUTH is used. If this option is omitted and a username is provided then the password will be prompted for.
-u, –username <username> Username to use when a URL is provided and HTTP BASIC AUTH is used.

list-runtimes

This command list runtimes in the tc Server Runtime Repository. The tc Server Runtime Repository contains past and current tc Runtime versions which are are compatible with the current version of tc Server.

Usage:

tcserver list-runtimes [OPTIONS]
Table 18. list-runtimes options
Option Description
-r, –runtimes-directory <directory> Custom directory containing tc Runtimes. This option is not required to run the list-runtimes command, even if a custom directory is used. This option is solely used for determining if the tc Runtime version is already installed.

list-templates

This command lists available templates in the tc Server template repository. The tc Server template repository is a repository of third party templates maintained by Pivotal Software.

Usage:

tcserver list-templates

support-bundle

This command builds a zip archive of common files requested by tc Server Support. The files included in this bundle are the following:

  • conf/catalina.properties
  • conf/context.xml
  • conf/logging.properties
  • conf/server.xml
  • conf/web.xml
  • logs/catalina.out
  • logs/tcruntime-instance.log
  • logs/threaddump.log (used by the thread-dump command)

The archive is created in the current directory and has a name matching the instance name with the current date appended to the name.

Usage:

tcserver support-bundle [OPTIONS]
Table 20. support-bundle options
Option Description
–exclude <files> List of files, separated by spaces, which should be excluded. This option must be specified after the instance-name. If a file is in both the –include and –exclude list it will be excluded.
-i, –instance-directory Specifies the directory which contains the instance. The default directory is the current directory. This references the parent directory of the instance.
–include <files list of files, separated by spaces, which should be added to the archive in addition to the default files. This option must be specified after the instance-name.

thread-dump

This command issues a thread dump to the JVM an instance is running in. The output is logged in logs\threaddump.log.

The –count and –interval options are useful for diagnostics.

Usage:

tcserver thread-dump [OPTIONS]
Table 21. thread-dump options
Option Description
–count <count> Number of thread dumps to issue. The default is one.
-i, –instances-directory Specifies the directory which contains the instance. The default directory is the current directory. This references the parent directory of the instance.
–interval <interval The interval in seconds to wait between thread dumps. This option is only considered when –count is above 1.
–java-home <directory> Specifies the JAVA_HOME to use for the jstack command. This option is only required when the instance’s JAVA_HOME is set to a JRE instead of a JDK.

help

This command shows help information on a command

Usage:

tcserver help <command>

version

This command shows either the tc Runtime version used by an instance or the tc Server version of the tcserver command itself.

Usage:

To show the version of an instance

tcserver version <instance-name>

To show the version of tc Server

tcserver version