Starting and Stopping tc Server Instances

This section describes how to start and stop tc Server instances on both Windows and Unix platforms. The following sections describe using the tcserver-ctl.sh|bat command script to start and stop the instances interactively, as well as how to configure your computer so the instances start and stop automatically without you having to specifically run the command script:

After you installed the tc Server application server, you had the option of using the SpringSource layout or the standard Apache (ASF) layout. These two types of tc Server are essentially the same, but differ slightly in their directory structure; see Differences between the SpringSource and ASF Layouts of tc Server for more information. For this reason, the Unix or Windows sections are further sub-divided into sections for each type of layout.

Unix: Starting and Stopping Instances Interactively Using tcserver-ctl.sh

To take full advantage of the tc Server features, such as deadlock detection, you must start tc Server using version 1.6 of the JDK.

If you are using the SpringSource layout and specified the --javahome path_to_jdk_1.6 option when creating a new instance using the tcserver-instance.sh script, then you are all set. If, however, you are using the ASF layout, or you didn't specify the --javahome option for the SpringSource layout, then you can manually update the file called setenv.sh in the CATALINA_BASE/bin directory and add a line to the file that specifies the value of the JAVA_HOME variable. For example:

export JAVA_HOME=/home/java/jdk1.6.0_12

You can set other environment variables in this file too, such as JAVA_OPTS and CATALINA_OPTS to specify properties for the JVM on which tc Server runs. See the file CATALINA_HOME/bin/setenv.sh for an example.

To download and install Sun Microsystem's JDK 1.6, see Java SE Downloads.

SpringSource Layout

If you are using the SpringSource layout of tc Server, you must first create a tc Server instance using the tcserver-instance.sh command script, as described in Creating a New tc Server Instance. The default installation of tc Server of the SpringSource layout does not include a server instance.

By default, this script creates all tc Server instances under the INSTALL_DIR/tcServer-6.0 directory, where INSTALL_DIR refers to the directory in which you installed tc Server, such as /home/tcserver. Each particular server instance lives in its own directory; this directory translates into the server's CATALINA_BASE variable. This is, of course, the default behavior of the command script; you might, however, have specified a different location of your tc Server instance.

In the SpringSource layout, CATALINA_HOME is INSTALL_DIR/tcServer-6.0/tomcat-version, where version refers to the version of tc Server, such as /home/tcserver/tcServer-6.0/tomcat-6.0.20.C.

To start and stop tc Server instances that use the SpringSource directory structure layout, follow these steps:

  1. Start a terminal window and change to the CATALINA_BASE/bin directory of the tc Server you want to start or stop.

    For example, if you installed tc Server in /home/tcserver and created a new tc Server instance called myserver:

    prompt$ cd /home/tcserver/tcServer-6.0/myserver/bin
  2. Start tc Server instance by executing the tcserver-ctl.sh start command. For example:

    prompt$ ./tcserver-ctl.sh start

    This command starts the tc Server as a daemon under the current user account.

  3. Stop a currently running tc Server instance by executing the tcserver-ctl.sh stop command:

    prompt$ ./tcserver-ctl.sh stop

See tcserver-ctl Command Reference for the full list of commands of the tcserver-ctl script.

ASF Layout

To stop and start tc Server instances in the ASF layout, follow these steps:

  1. Start a terminal window and change to the CATALINA_HOME/bin directory of the tc Server you want to start or stop.

    For example, if you installed tc Server in /home/tcserver and are using version 6.0.20.C of tc Server:

    prompt$ cd /home/tcserver/tcServer-6.0/tomcat-6.0.20.C/bin
  2. Start tc Server by executing the tcserver-ctl.sh start command. For example:

     prompt$ ./tcserver-ctl.sh start

    This command starts the tc Server as a daemon under the current user account.

  3. Stop a currently running tc Server by executing the tcserver-ctl.sh stop. For example:

    prompt$ ./tcserver-ctl.sh stop

See tcserver-ctl Command Reference for the full list of commands of the tcserver-ctl script.

NOTE: The ASF layout of tc Server also includes the standard Apache Tomcat script for starting and stopping the server: catalina.sh. This script is provided for users who are already familiar with Apache Tomcat and would prefer to continue using the same script to start and stop the server.

The two methods of starting the server (catalina.sh start and tcserver-ctl.sh start) are essentially the same. However, the two methods of stopping the server differ in the following important way: catalina.sh stop takes into account the value of the SHUTDOWN port and if it is -1, the script does not stop the server. The tcserver-ctl.sh stop command, however, stops the server even if its SHUTDOWN port is set to -1.

Unix: Automatically Starting Instances at System Boot Time

On Unix platforms, the tc Server installation includes a command script file called INSTALL_DIR/tcServer-6.0/boot.rc.template, which is a template file that you can use to customize your Unix boot process so that tc Server instances start automatically when your computer starts. It is assumed that you already know how to customize the Unix boot process for your particular platform, so this section does not go into detail about where you should put this particular boot file (although typically you rename the file something like boot.rc and put it in the /etc/rc.d directory.) Rather, this section describes the updates you should make to the boot template file to reflect your tc Server instance environment. Consult your Unix administration documentation for further details about customizing the boot process.

There is a one-to-one relationship between a boot.rc file and a tc Server instance. This means, for example, that if you want to automatically start multiple tc Server instances on the same Unix computer, you must create separate boot.rc files for each server instance, modify each of them to reflect the environment of the corresponding tc Server instance, and then put each of these files in the appropriate boot directory.

Edit only the top part of the boot.rc.template file that sets the following environment variables:

The following example shows how to specify that the tc Server home directory is /home/tcserver/tcServer-6.0, that the instance directory is the same as the tc Server home directory, that the instance name is myserver, that the JDK is located in /home/java/jdk1.6.0_11 and that you want the tomcat user to start the tc Server process:

TOMCAT_USER=tomcat
TC_SERVER_HOME=/home/tcserver/tcServer-6.0
INSTANCE_BASE=$TC_SERVER_HOME
INSTANCE_NAME=myserver
JAVA_HOME=/home/java/jdk1.6.0_11

Be sure you do not modify any part of the boot.rc.template file after the text DO NOT EDIT BEYOND THIS LINE.

Windows: Starting and Stopping Instances As Windows Services

To take full advantage of the tc Server features, such as deadlock detection, you must start the tc Server instance using version 1.6 of the JDK.

If you are using the SpringSource layout and specified the --javahome path_to_jdk_1.6 option when creating a new instance using the tcserver-instance.bat script, then you are all set. If, however, you are using the ASF layout, or you didn't specify the --javahome option for the SpringSource layout, then you can manually update the file called setenv.bat in the CATALINA_BASE\bin directory and add a line to the file that specifies the value of the JAVA_HOME variable. For example:

set JAVA_HOME=c:\home\java\jdk1.6.0_12

You can set other environment variables in this file too, such as JAVA_OPTS and CATALINA_OPTS to specify properties for the JVM on which tc Server runs. See the file CATALINA_HOME\bin\setenv.bat for an example.

To download and install Sun Microsystem's JDK 1.6, see Java SE Downloads.

SpringSource Layout

If you are using the SpringSource layout of tc Server, you must first create a tc Server instance using the tcserver-instance.bat command script, as described in Creating a New tc Server Instance. The default installation of tc Server (SpringSource) does not include a server instance.

By default, this script creates all tc Server instances under the INSTALL_DIR\tcServer-6.0 directory, where INSTALL_DIR refers to the directory in which you installed tc Server, such as c:\home\tcserver. Each particular server instance lives in its own directory; this directory translates into the server's CATALINA_BASE variable. This is, of course, the default behavior of the command script; you might, however, have specified a different location of your tc Server instance.

In the SpringSource layout, CATALINA_HOME is INSTALL_DIR\tcServer-6.0\tomcat-version, where version refers to the version of tc Server, such as c:\home\tcserver\tcServer-6.0\tomcat-6.0.20.C.

To start and stop tc Server instances that use the SpringSource directory structure layout, follow these steps:

  1. Start a commmand prompt and change to the CATALINA_BASE\bin directory of the tc Server you want to start or stop.

    For example, if you installed tc Server in c:\home\tcserver and created a new tc Server instance called myserver:

    prompt$ cd c:\home\tcserver\tcServer-6.0\myserver\bin
  2. Install tc Server as a Windows service by executing the following command:

    prompt$ tcserver-ctl.bat install

    Once installed as a Windows service you use the Windows Services console to stop and start the service. It is displayed in the Windows Services console with the name SpringSource tcServer - Server servername.

  3. To uninstall the tc Server service, execute the following command:

    prompt$ tcserver-ctl.bat uninstall

Although SpringSource recommends that you always install tc Server as a Windows service and stop and start it using the Services console, you can also stop and start the server instance manually. See tcserver-ctl Command Reference for the full list of commands of the tcserver-ctl script.

ASF Layout

To stop and start tc Server instances in the ASF layout, follow these steps:

  1. Start a commmand prompt and change to the CATALINA_HOME\bin directory of the tc Server you want to start or stop.

    For example, if you installed tc Server in c:\home\tcserver and are using version 6.0.20.C:

    prompt$ cd c:\home\tcserver\tcServer-6.0\tomcat-6.0.20.C\bin
  2. Install tc Server as a Windows service by executing the following command:

    prompt$ tcserver-ctl.bat install 

    Once installed as a Windows service you use the Services Window control panel to stop and start the service. It is displayed in the Services Window with the name SpringSource tcServer.

  3. To uninstall the tc Server service, execute the following command:

    prompt$ tcserver-ctl.bat uninstall

Although SpringSource recommends that you always install tc Server as a Windows service and stop and start it using the Services console, you can also stop and start the server instance manually. See tcserver-ctl Command Reference for the full list of commands of the tcserver-ctl script.

NOTE: The ASF layout of tc Server also includes the standard Apache Tomcat script for starting and stopping the server: catalina.bat. This script is provided for users who are already familiar with Apache Tomcat and would prefer to continue using the same script to start and stop the server.

The two methods of starting the server (catalina.bat start and tcserver-ctl.bat start) are essentially the same. However, the two methods of stopping the server differ in the following important way: catalina.bat stop takes into account the value of the SHUTDOWN port and if it is -1, the script does not stop the server. The tcserver-ctl.bat stop command, however, stops the server even if its SHUTDOWN port is set to -1.

The Windows Java Service Wrapper

On Windows, tc Server uses a Java Service Wrapper from Tanuki Software to install the tc Server instance as a Windows service. The Wrapper correctly handles user log outs under Windows, service dependencies, and the ability to run services which interact with the desktop.

The wrapper is configured using the CATALINA_BASE\conf\wrapper.conf file, where CATALINA_BASE is the top-level directory of the server instance, such as c:\home\tcserver\tcServer-6.0\myserver. In most circumstances, there is no need for you to update this file because the default one created when you created the tc Server instance handles most use cases. However, you might sometimes want to further customize the Windows service to fit particular circumstances of your environment; in which case you can edit the wrapper.conf file.

Important: When you start a tc Server instance on Windows using the tcserver-ctl.bat command script, the script might override the following parameters of the wrapper.conf file with instance-specific values:

This means, for example, that although the wrapper.conf file might appear to set the ARCH parameter to win32, the tcserver-ctl.bat script overrides this generic value with something else (such as winx86_64) if in fact you are running the tc Server instance on a 64-bit computer.

For details about the available configuration properties, see Configuration Property Overview.

tcserver-ctl Command Reference

You use the tcserver-ctl.sh (Unix) and tcserver-ctl.bat (Windows) command script to manage tc Server instances.

Typically, you run the command from the bin directory of the server instance itself. However, you can also run it from the INSTALL_DIR/tcServer-6.0 directory if you specify the name of the instance, where INSTALL_DIR refers to the directory in which you installed tc Server.

For example, to start a tc Server instance called myserver from the bin directory of the instance itself on Unix, run the following commands:

prompt$ cd /home/tcserver/tcServer-6.0/myserver/bin
prompt$ ./tcserver-ctl.sh start

You can accomplish the same thing by running the command from the tcServer-6.0 directory by specifying the name of the instance:

prompt$ cd /home/tcserver/tcServer-6.0
prompt$ ./tcserver-ctl.sh myserver start

It is assumed in the remainder of this section, however, that you are running the command script from the bin directory of the tc Server instance.

The following table lists the commands and options of the tcserver-ctl script. The table also indicates whether the command is supported on Unix, Windows, or both.

Command Description Platform
install run-as-user Installs the tc Server instance as a Windows service. You then start and stop the service using the Windows Service console.

The optional run-as-user parameter specifies the user account that you want the tc Server service to actually run as when you start the service using the Windows Service console; if you do not specify this parameter, then the user account that initially installed it is used. Note that you can specify only user accounts that have their Logon as Service right set to run a Windows service; for details on how to set this for a particular user, see Setting the Logon As Service Right for a Windows User.

When you run this command and explicitly specify a run-as-user user, the script asks you for the password of the specified user. Note that tc Server still installs the instance as a service, even if you enter an incorrect password. However, when you try to start the service, it will fail with a logon error. To fix the problem, you must then uninstall the service, then reinstall it with the correct password.

Windows only
uninstall Uninstalls the tc Server instance from the Windows Service. Windows only
start Starts the tc Server instance as a daemon process.

On Windows, you must have previously installed the tc Server instance as a Windows service to be able to start it using the tcserver-ctl.bat start command; see the documentation on the tcserver-ctl.bat install command in this table for more information.

Unix and Windows
restart Stops, and then immediately starts, a running tc Server instance. As with the start command, restart starts the instance as a daemon process.

On Windows, you must have previously installed the tc Server instance as a Windows service to be able to restart it using the tcserver-ctl.bat restart command; see the documentation on the tcserver-ctl.bat install command in this table for more information.

Unix and Windows
run Starts the tc Server instance as a foreground process. Unix and Windows
batch Runs the tc Server instance using the catalina.bat script as a batch job. Specifically, the script starts the tc Server instance by running the following command: %CATALINA_HOME%\bin\catalina.bat run. Windows only
stop timeout Stops a running tc Server instance. By default, the tcserver-ctl script waits for 5 seconds and checks to see if the process has exited gracefully; if it has not, then the script forces a termination of the process.

You can set your own timeout value by specifying an integer option for the number of seconds; for example:

prompt$ ./tcserver-ctl.sh stop 10

Unix and Windows
status Reports the status of a tc Server instance, such as whether it is running or stopped, as well as useful information such as the directory from which the tc Server instance gets its binary files, the main instance source directory, and so on. Unix and Windows

Setting the Logon As Service Right for a Windows User

This section applies to Windows platforms only.

The tcserver-ctl.bat install command has an optional run-as-user parameter with which you can specify the user account that you want the tc Server service to actually run as when you start the service using the Windows Service console. Windows requires that the specified user account must have their Logon as Service right set for this feature to work properly. To set this right, follow these steps:

  1. From the Windows Start menu, open the Control Panel.
  2. Open Administrative Tools.
  3. Open the Local Security Policy tool.
  4. Expand the Local Policies settings.
  5. Click the User Rights Assignment.
  6. On the right side, double-click on the Log on as a service policy.
  7. Click on the Add User Or Group button and enter the user account name using the wizard.

Note that the Local Security Policy tool does not appear to be available on Home versions of Windows 2000 and XP. It is thus not possible to run the tc Server service as a specific account under those versions of Windows.