Starting and Stopping tc Runtime Instances

The following sections describe how to start and stop tc Runtime instances on both Unix and Windows platforms.

On Unix platforms, you typically use shell scripts to start and stop tc Runtime instances; alternatively, you can configure your Unix boot process to start the instance automatically. On Windows, you first install the tc Runtime instance as a Windows Service. You can use the tcruntime-ctl script or the Windows Services console to start and stop it.

Unix: Starting and Stopping tc Runtime Instances Interactively Using tcruntime-ctl.sh

By default, the tcruntime-instance.sh script creates all tc Runtime instances under the INSTALL_DIR/vfabric-tc-server-edition directory, where INSTALL_DIR refers to the directory in which you installed tc Server, such as /opt/vmware, and edition refers to the edition or package of tc Server you are using (developer or standard). Each tc Runtime instance lives in its own directory; this directory translates into the server's CATALINA_BASE variable. This is the default behavior of the command script; you might have specified a different location of your tc Runtime instance.

In the following procedure, it is assumed that you installed a tc Server Standard Edition.

To start and stop a tc Runtime instance:

  1. Login to the computer on which installed tc Server as the user who will run the tc Runtime instance, such as tcserver. On Unix, if you have disabled interactive login, login as the root user and use su - tcserver to become the user.

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

    For example, if you installed tc Server in /opt/vmware and created a new tc Runtime instance called myserver in the /var/opt/vmware/vfabric-tc-server-standard directory:

    prompt$ cd /var/opt/vmware/vfabric-tc-server-standard/myserver/bin
  3. Start the tc Runtime instance by executing the tcruntime-ctl.sh start command. For example:

    prompt$ ./tcruntime-ctl.sh start

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

  4. Stop a currently running tc Runtime instance by executing the tcruntime-ctl.sh stop command:

    prompt$ ./tcruntime-ctl.sh stop

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

Unix: Starting tc Runtime Instances Automatically at System Boot Time

When you create a tc Runtime instance on a Unix platform, the tcruntime-instance.sh script creates a boot script, instance-name/bin/init.d.sh, which you can install to start the tc Runtime instance automatically at boot time. Once you install the script, whenever the computer reboots, the tc Runtime instance is automatically started. You can also use the script to control the tc Runtime instance the same way you use other scripts in the /etc/init.d directory.

About Users and Permissions

The scripts in /etc/init.d are owned by root and must be executed by root. When the tc Runtime init.d script executes, it uses /bin/su to execute the tc Runtime instance as another user, tc-server by default. This user account must exist and have permission to read and write all files in the CATALINA_HOME directory.

To ensure that file permissions are correct, you should either create the tc Runtime instance while logged in as the user you want to run the instance, or create the instance and then chown the CATALINA_HOME directory and all of its files and subdirectories to the user you want to run the instance.

Specify the runtime user on the tcruntime-instance.sh create command line when you create the instance by including --property base.runtime.user=run-time-user in the command, as shown in this example:

prompt$ ./tcruntime-instance.sh create --property base.runtime.user=tcserver \
	-i /var/opt/vmware/vfabric-tc-server-standard myInstance

Or use the --interactive option, and the tcruntime-instance.sh create command will prompt you to enter the runtime user account.

After you create an instance, you can edit the CATALINA_HOME/bin/init.d.sh file and change the value of the TC_RUNTIME_USER variable:

TC_RUNTIME_USER="tc-server"

Again, ensure that the user exists and owns (or is able to read and write) all files and directories in the CATALINA_HOME directory.

Installing the init.d.sh Script

To enable the init.d.sh script, you create a link to it in the /etc/init.d directory. Since the scripts in /etc/init.d belong to root, this procedure requires root permission.

Note

Do not copy the init.d.sh file into the /etc/init.d directory. The script depends on its location in the bin directory of the tc Runtime instance.

Procedure
  1. In a Unix terminal window, use the su command to become root, if necessary:

    prompt$ su
    Password:

    Enter the root password at the prompt.

  2. Install the init.d.sh script in the /etc/init.d directory using a command like the following:

    prompt# ln -s CATALINA_HOME/bin/init.d.sh /etc/init.d/instance-name

    For example, if you created an instance named MyInstance in the /var/opt/vmware/vfabric-tc-server-standard directory, enter this command:

    prompt# ln -s /var/opt/vmware/vfabric-tc-server-standard/MyInstance/bin/init.d.sh \
            /etc/init.d/MyInstance
  3. To test the script, restart the computer, or start the tc Runtime instance using the /etc/init.d/instance-name command. For example:

    prompt# /etc/init.d/MyInstance start
  4. Check the status of the tc Runtime instance using the /etc/init.d/instance-name status command. For example:

    prompt# /etc/init.d/MyInstance status

Using the /etc/init.d Script

If you are accustomed to using commands in /etc/init.d to start, stop, and restart services, you can do the same with tc Runtime instances. Internally, the /etc/init.d/instance-name script calls the tcruntime-ctl.sh script in the tc Runtime instance's bin directory, so the options are equivalent. The /etc/init.d/instance-name script supports the commands in the following table:

Table 13. init.d Commands for tc Runtime Instances

CommandDescription
startStarts the Instance
stopShuts down the instance
restartStops and starts the instance
statusDisplays information about the tc Runtime instance and whether it is running or not running.

You must be root when you execute the command. For example, to restart a tc Runtime instance named MyInstance:

prompt$ sudo /etc/init.d/MyInstance restart

Windows: Starting and Stopping tc Runtime Instances as Windows Services

By default, the tcruntime-instance.bat script creates all tc Runtime instances under the INSTALL_DIR\vfabric-tc-server-edition directory, where INSTALL_DIR refers to the directory in which you installed tc Server, such as \opt\vmware and edition is developer or standard. Each particular tc Runtime instance lives in its own directory; this directory translates into the server's CATALINA_BASE variable. This is the default behavior of the command script; you might have specified a different location of your tc Runtime instance. If so, adjust the following procedure accordingly.

In the following procedure, it is assumed that you installed a tc Server Standard Edition.

To start and stop tc Runtime instances as Windows Services:

  1. Login to the computer on which you installed tc Server as the userwho will run the tc Runtime instance, such as tcserver.

  2. If this is the first time that you will install and start the tc Runtime instance after creating it, start a Command Prompt window and continue with this procedure.

    If you have already installed the tc Runtime instance as a Windows Service, use the Windows Services control panel to start and stop it.

  3. Change to the CATALINA_BASE\bin directory of the tc Runtime instance you want to start or stop.

    For example, if you installed tc Server in \opt\vmware and created a new tc Runtime instance called myserver in the \var\opt\vmware\vfabric-tc-server-standard directory:

    prompt> cd \var\opt\vmware\vfabric-tc-server-standard\myserver\bin
  4. Install the tc Runtime instance as a Windows service:

    prompt> tcruntime-ctl.bat install

    The command installs the tc Runtime instance as an automatic Windows Service, which means that the tc Runtime instance starts automatically when you start the Windows computer. You can change this behavior using the Windows Service control panel.

    You should see a message indicating a successful installation:

    wrapper | SpringSource tc Runtime - tcserver-c-var-opt-vmware-vfabric-tc-server-standard-myserver installed.

  5. Start and stop the tc Runtime instance using the tcruntime-ctl.bat script or the Windows Services console. The tc Runtime instance is displayed in the console with the name SpringSource tc Runtime - unique-name, where unique-name is a unique combination of server name and server directory.

    To start an instance using tcruntime-ctl.bat:

    prompt> tcruntime-ctl.bat start

    To stop an instance using tc-runtime-ctl.bat:

    prompt> tcruntime-ctl.bat stop

To uninstall the tc Runtime service, execute the following command:

prompt> tcruntime-ctl.bat uninstall

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

Windows Java Service Wrapper

On Windows, tc Runtime uses a Java Service Wrapper from Tanuki Software to install the tc Runtime instance as a Windows service. The Wrapper correctly handles user logouts 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 tc Runtime instance, such as \var\opt\vmware\vfabric-tc-server-standard\myserver. In most circumstances, you do not need to update this file because the default one created when you created the tc Runtime 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.

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

tcruntime-ctl Command Reference

You use the tcruntime-ctl.sh (Unix) and tcruntime-ctl.bat (Windows) command scripts to manage tc Runtime instances. The syntax of the script is as follows:

tcruntime-ctl.sh|bat command [option]

Typically, you run the command from the bin directory of the tc Runtime instance itself. However, you can also run it from the INSTALL_DIR/vfabric-tc-server-edition directory if you specify the name of the instance, where INSTALL_DIR refers to the directory in which you installed tc Server and edition refers the edition of tc Server (developer or standard.)

For example, to start a tc Runtime instance called myserver from the bin directory of the instance itself on Unix:

prompt$ cd /var/opt/vmware/vfabric-tc-server-standard/myserver/bin
prompt$ ./tcruntime-ctl.sh start

You can accomplish the same thing by running the command from the main installation directory by specifying the name of the instance and its location with the -n option:

prompt$ cd /opt/vmware/vfabric-tc-server-standard
prompt$ ./tcruntime-ctl.sh myserver start -n /var/opt/vmware/vfabric-tc-server-standard

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

The following table describes the tcruntime-ctl script commands and supported platforms.

Table 14. Commands of the tcruntime-ctl Script

CommandDescriptionPlatform
install run-as-userInstalls the tc Runtime 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 Runtime 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. You can specify only user accounts that have their Logon as Service right set to run a Windows service. 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. tc Runtime still installs the instance as a service, even if you enter an incorrect password. However, when you try to start the service, it fails with a logon error. You must uninstall the service and reinstall it with the correct password.

Windows only
uninstallUninstalls the tc Runtime instance from the Windows Service.Windows only
startStarts the tc Runtime instance as a daemon process.

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

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

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

By default, the tcruntime-ctl script (when stopping the tc Runtime instance) waits for up to 60 seconds for the process to exit gracefully. If the server process exits earlier, the script proceeds to restart the server. If the process has not exited by the end of the timeout period, the script forces a termination of the process before restarting the server. Using the optional timeout parameter, you can set your own timeout value by specifying an integer option for the number of seconds. For example, to specify that you want the instance to stop after 10 seconds:

prompt$ ./tcruntime-ctl.sh restart 10

Unix and Windows
runStarts the tc Runtime instance as a foreground process.Unix and Windows
batchRuns the tc Runtime instance using the catalina.bat script as a batch job. Specifically, the script starts the tc Runtime instance by running the following command: %CATALINA_HOME%\bin\catalina.bat run.Windows only
stop timeoutStops a running tc Runtime instance. By default, the tcruntime-ctl script waits for up to 60 seconds for the process to exit gracefully; if it has not, then the script forces a termination of the process.

Using the optional timeout parameter, you can set your own timeout value by specifying an integer option for the number of seconds. For example, to specify that you want the instance to stop after 10 seconds:

prompt$ ./tcruntime-ctl.sh stop 10

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

The following table describes the options you can use with the tcruntime-ctl script. All the options are optional; you can use them with any of the tcruntime-ctl commands.

Table 15. Options of the tcruntime-ctl Script

OptionDescription
-d tcRuntimeDirReplace tcRuntimeDir with the full pathname of the tc Server installation directory. Use this option if you are running the tcruntime-ctl.sh|bat script from a location other than its default location.

The default value of this option is the location of the tcruntime-ctl.sh|bat script.

-n instanceDirReplace instanceDir with the full pathname of the parent of the tc Runtime instance directory. Use this option if the tc Runtime instance directory is not in the default location (i.e., the main tc Server installation directory).

For example, if the full instance directory of a tc Runtime instance is /var/opt/vmware/vfabric-tc-server-standard/myserver, then you would specify /var/opt/vmware/vfabric-tc-server-standard for this option.

The default value of this option is the current working directory.


The following example shows how to stop the tc Runtime instance called myserver, located in the /var/opt/vmware/vfabric-tc-server-standard directory, after waiting for up to 60 seconds:

prompt$ cd /var/opt/vmware/vfabric-tc-server-standard/myserver/bin
prompt$ ./tcruntime-ctl.sh stop 60

In the following example, use of the -n option indicates that the tc Runtime instance called myotherinstance has an instance directory of /var/opt/vmware/vfabric-tc-server-standard/myotherinstance. The example shows how to use the tcruntime-ctl script located in the main tc Server installation directory.

prompt$ cd /opt/vmware/vfabric-tc-server-standard
prompt$ ./tcruntime-ctl.sh myotherinstance stop 60 -n /var/opt/vmware/vfabric-tc-server-standard

Windows: Setting the Logon-as-Service Right for a Windows User

The tcruntime-ctl.bat install command has an optional run-as-user parameter by which you specify the user account that you want the tc Runtime service to run as when you start the service from 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:

  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.

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 Runtime service as a specific account under those versions of Windows.