Nav

Installing Tcat Server

This section includes instructions for all supported Tcat Server scenarios.

Prerequisites

Operating System Requirements

Tcat Server has been tested on the following operating systems:

  • Windows: XP, Server 2003, Vista, Server 2008, Windows 7

  • Linux: RHEL 4 & 5, CentOS 4 & 5, Oracle 5, Fedora 6 through 13, Ubuntu 9.x and 10.x, SUSE 10 & 11, openSUSE 10 & 11

  • Mac OS X: 10.5.8 and 10.6

  • Solaris: All versions that have a supported Java runtime, server restarts are supported on Solaris 10 and 11

  • Java 1.6 and newer including 1.8

Java Runtime Requirements

You may download Tcat Server with or without a bundled JRE. If you install the installer package that comes with a bundled JRE, you do not need to install any other Java runtime. If you instead install the installer package that has no bundled JRE, you must install a separate Java runtime (JDK or JRE, either one works). On startup, Tcat Server uses the Java runtime that is pointed to by the JAVA_HOME or JRE_HOME environment variable. If neither of these environment variables points to a Java runtime, then Tcat Server automatically uses the bundled JRE. Check the value of the JAVA_HOME and JRE_HOME variables on your server, since either or both may already point to a Java runtime that is already installed. Tcat Server tries to use JAVA_HOME first, and if Java runtime isn’t found, Tcat next tries JRE_HOME.

If you are installing and using your own JDK or JRE (instead of using the bundled JRE), ensure that you have a JDK or JRE 1.5.x or newere installed and that your JAVA_HOME or JRE_HOME environment variable is set correctly. For example, on Windows, choose the System utility from the Control Panel, click the Advanced tab, click Environment Variables, and then add the JAVA_HOME or JRE_HOME system variable.

MuleSoft recommends the latest Oracle/Sun Hotspot 1.6.0 JDK or JRE for Tcat Server or newer, but has also tested the IBM J9 1.6.0 and Oracle JRockit 1.6.0 JVMs and newer.

Tcat Server can run in two or more different Java VMs:

  1. The Tcat Server console runs in Tomcat 6.0 and newer, and requires Java 1.6.0 and newer (also known as "Java 6"). Java 1.5.0 runtimes do not work.

  2. The Tcat Server agents can run in any Tomcat 5.5 or newer, and JRE/JDK require Java 1.5.0 or newer, meaning Java 1.6 runtimes are both supported and recommended.

Here are some Java runtimes we’ve tested and are known to work with Tcat Server:

  • Oracle/Sun Hotspot version 1.5.0 JDKs or JREs and newer (except as noted below)

  • Oracle/Sun Hotspot version 1.6.0_04 and newer JDKs or JREs

  • Oracle/JRockit version 1.6.0_20 and newer JDK (Tcat v6.4.1 and older console logs tab shows zero logs)

  • OpenJDK version 1.6.0_18 openjdk-6-jdk "(IcedTea6 1.8) (6b18-1.8-0ubuntu1)" on Ubuntu 10.04 Linux

  • OpenJDK version 1.6.0_0-2b12 on Linux

  • IBM J9 version 1.6.0 or newer JDK or JRE (this works with Tcat Server v6.4.2 and newer)

  • Apple JDK 1.6.0, all versions

Here are some JDKs we tested that are known not to work, and are unsupported:

  • Oracle/Sun JDK or JRE versions 1.6.0_03 or older (due to JAXB, any 1.6.0 Oracle/Sun Hotspot JVM older than 1.6.0_04 won’t work)

  • IBM J9 1.5.0 JDK and JRE (due to lack of support for self-signed HTTPS client certificates)

  • OpenJDK versions older than 1.6.0_0-2b12 on Linux (prone to JVM crashes and other JVM failures)

  • GNU GCJ or GIJ, all versions

Older Linux distribution versions tend to contain incompatible Java runtimes that are known not to run Tcat Server. Tcat Server is incompatible with these Java runtimes, including all versions of GCJ, any version of IcedTea older than version 6, and OpenJDK versions older than version 1.6.0.0-b17, though version 1.6.0_0-2b12 were tested to work.

Red Hat Enterprise Linux / CentOS / Fedora

Before installing Tcat Server on a 64-bit installation, you must have the 32-bit compatibility libraries and all of their dependencies installed. You may install them via yum like this for most versions of RHEL, CentOS, and Fedora:


           
        
1
2
3
$ sudo -s
# yum install compat-libstdc++-33.i586 gtk+.i586 gtk2.i586
# exit

Or, like this for some newer versions of these distributions:


           
        
1
2
3
$ sudo -s
# yum install compat-libstdc++-33.i686 gtk+.i686 gtk2.i686
# exit

Then, you may proceed with installing Tcat Server via the installer executable.

Ubuntu Linux

Before installing Tcat Server on a 64-bit installation of Ubuntu, you must have the 32-bit compatibility libraries and all of their dependencies installed. You may install them via apt-get like this:


           
        
1
2
3
$ sudo -s
# sudo apt-get install ia32-libs
# exit

Then, you may proceed with installing Tcat Server via the installer executable.

OpenSUSE Linux

Before installing Tcat Server on a 64-bit installation of OpenSUSE 11, you must have the 32-bit versions of GTK2 and all of its dependencies installed. You may install them using yast, like this:


           
        
1
2
3
$ sudo -s
# yast -i gtk2-32bit
# exit

Then, you may proceed with installing Tcat Server via the installer executable.

QuickStart Installation

The QuickStart section includes instructions for all supported operating systems, and explains a few basic configurations to get you started working with Tcat Server. The remainder of this section includes instructions for special use cases and OS-specific configurations.

Upgrade Installation

To upgrade an existing installation of Tcat Server version 6.2, follow these instructions.

If you are upgrading from a previous release, see Upgrading to R4 instead.

Automated Installation

The Tcat Server installers are available for Windows, Linux, Solaris, and Mac OS X. These installers allow you to install Tomcat, the Tcat Server agent, the Tcat Server administration console, and each installs a preconfigured version of Tomcat, saving you some manual steps.

Headless Installation

This section describes how to install Tcat Server in a "headless" (text-only) mode. When you install Tcat in headless mode, the Tcat installer asks you questions in the shell about the installation directory, the server ports, etc. The installer begins to install only after you answer all of the installation questions in the shell. If you need to automate the settings, this section also describes how you can perform a headless non-interactive installation.

On Windows, run this command to install Tcat Server in headless mode:


         
      
1
C:\> start /wait tcat-installer-6.4.3-windows-64bit.exe -c

On Linux and Solaris, run this command to install Tcat Server in headless mode:


         
      
1
# sh tcat-installer-6.4.3-*.sh -c

The installer’s interaction in the shell looks like this:


         
      
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# sh tcat-installer-6*.sh -c
Unpacking JRE ...
Preparing JRE ...
Starting Installer ...
This installs Tcat Server 6 on your computer.
OK [o, Enter], Cancel [c]
 
Read the following License Agreement. You must accept the terms of this agreement before continuing with the installation.
...
 
I accept the agreement
Yes [1], No [2]
1
Which type of installation should be performed?
Standard installation [1, Enter]
Custom installation [2]
1
Where should Tcat Server 6 be installed?
[/opt/TcatServer6]

With the -c argument, the installer asks you to select your choices in text mode prompts. If you instead want to accept all defaults including installing the Administration Console and using all of the default port numbers, use the -q argument instead:


         
      
1
# sh tcat-installer-6.4.3-*.sh -q

Or, to feed responses to the installer, so that it doesn’t need to ask anything:


         
      
1
# sh tcat-installer-6.4.3-*.sh -q -varfile response.varfile

The response.varfile is generated inside the .install4j directory when we first run the installer. The contents of the varfile is the same format as a simple Java properties file:


         
      
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# less /opt/TcatServer6/.install4j/response.varfile
 
#install4j response file for Tcat Server 6 R4 P1
#Fri Sept 27 16:51:39 GMT-08:00 2010
tcatServiceName=tcat6
secureAgentPort$Long=51443
tomcatHttpPort$Long=8080
tomcatHttpsPort$Long=8443
tomcatShutdownPort$Long=8005
tomcatAjpPort$Long=8009
sys.installationDir=/opt/TcatServer6
sys.programGroup.linkDir=/usr/local/bin
sys.programGroup.name=Tcat Server 6 [tcat6]
sys.programGroup.enabled$Boolean=false
sys.programGroup.allUsers$Boolean=true
sys.languageId=en
sys.installationTypeId=39
sys.component.37$Boolean=true
sys.component.51$Boolean=true
sys.component.52$Boolean=true
sys.component.53$Boolean=true
sys.component.54$Boolean=true

You may also pass -Dinstall4j.debug=true and -Dinstall4j.detailStdout=true on the installer command line if you want Install4J’s debugging information about the installation. On Windows, you probably also want to pass -q -console as the first and second arguments or else you may not get the output in the shell. Read TcatServer6/.install4j/installation.log afterwards.

Add Tcat Server Capabilities to an Existing Apache Tomcat Installation

Installing Multiple Tcat Servers on a Single Computer

NOTE if you are connected to your network via a virtual private network (VPN), disconnect before running Tcat Server. After you have registered all your Tcat Server instances, you can connect to your VPN again.

Installation Options

This section includes a few procedures for customizing installs.

Make Contents of Webapps Directory Unwriteable

By default, the Administration Console enables a user to edit files on any Tcat Server instance registered to it.

This property is set in the spring-services.xml file in the webapps/agent/WEB-INF/ directory: Below is the relevant snippet:


          
       
1
2
3
4
5
6
7
8
9
<property name="writeExcludes">
  <list>
    <value>lib/catalina*.jar</value>
    <value>**/tomcat*.jar</value>
    <value>conf/tcat-overrides.conf</value>
    <!-- block the webapps directory -->
    <!-- <value>webapps/**</value> -->
  </list>
</property>

To disable this ability:

  1. Uncomment last element shown in the above snippet, replacing this

    
                 
              
    1
    
    <!-- <value>webapps/**</value> -->

    With this:

    
                 
              
    1
    
    <value>webapps/**</value>
  2. Save the file.

  3. Restart the Tcat Server instance.

Renaming the tcat6 Service on Linux

You may wish to rename your Tcat Server’s init script, either because you’re installing more than one copy of Tcat Server in a single operating system and you need to prevent an init script naming conflict, or because you want to invoke the init script using a different name. Tcat Server supports renaming the service.

First, make sure you shut down your Tcat/Tomcat instance whose service you want to rename:


          
       
1
$ sudo service tcat6 stop

Or, if you’re currently using a stock Tomcat package init script:


          
       
1
$ sudo service tomcat6 stop

Switch to a root shell:


          
       
1
$ sudo -s

Set the new service name as an environment variable, along with the absolute path to the directory to the Tcat Server installation you’re changing the service name for:


          
       
1
2
# export NEW_SERVICE_NAME=t1
# export TCAT_HOME=/opt/TcatServer6

Next, rename the init script symlinks to the new service name (copy and paste these commands – don’t type them in):


          
       
1
2
3
# mv /etc/init.d/tcat6 /etc/init.d/$NEW_SERVICE_NAME 2>/dev/null
# mv $TCAT_HOME/bin/tcat6 $TCAT_HOME/bin/$NEW_SERVICE_NAME 2>/dev/null
# mv $TCAT_HOME/conf/Catalina/localhost/tcat6 $TCAT_HOME/conf/Catalina/localhost/$NEW_SERVICE_NAME

If any of the above "tcat6" files do not exist, it is because you installed Tcat Server’s agent webapp only, which is okay. You must pair the agent with the console before the agent unpacks its service scripts.

And, in your Tcat/Tomcat instance’s environment file, which is used for the JVM’s startup environment, change the service name setting (copy and paste this command – don’t type it in):


          
       
1
2
# sed -i.bak -e "s/\-Dtcat\.service\=[Installation^ ]* /-Dtcat.service=$NEW_SERVICE_NAME /g" \
    $TCAT_HOME/conf/Catalina/localhost/tcat-env.conf

Exit from the root shell.


          
       
1
# exit

If you’re changing the service to install two or more Tcat Server installations in a single operating system, you should also ensure that the port numbers in Tomcat’s <tomcatHome>/conf/server.xml do not conflict, and also that the Tcat Server agent secure port number of each Tcat Server instance is unique (copy and paste these commands – don’t type them in):


          
       
1
2
3
# export NEW_AGENT_SECURE_PORT=51444
# sed -i.bak -e "s/^securePort=.*/securePort=$NEW_AGENT_SECURE_PORT/g" \
    $TCAT_HOME/webapps/agent/WEB-INF/agent.properties

Then inspect the agent.properties file to ensure the setting is correct.

The default agent secure port is 51443.

You’re now finished renaming the service. You can now start, stop, or restart Tcat Server using the service name you chose:


          
       
1
$ sudo service t1 start

Starting and Stopping Tcat Server

This section describes the simplest way to start and stop Tcat Server on Windows, Linux, and Solaris, additional options for each, instructions for Starting and Stopping on Mac OS X, and instructions for Starting the Administration Console.

If you want to use the standard Tomcat catalina or startup commands to start Tomcat, any environment variables you set in the Tcat Server console do not take effect until you restart Tomcat using the Tcat Server commands. Therefore, for best results when setting environment variables in the Tcat Server console, you should always start Tomcat using the Tcat Server commands described below.

Starting and Stopping on Windows and Linux

To start Tcat Server, navigate to the bin directory and enter the following at the prompt:


          
       
1
tcat6 start

Or prefix tcat6 with the path to the bin directory to run the command from a different directory. To start the administration console, see below.

To stop Tcat Server, simply close the command window, or use:


          
       
1
tcat6 stop

You can also restart the server:


          
       
1
tcat6 restart

and get the server’s status and process ID:


          
       
1
tcat6 status

Additional Options on Windows

If you installed Tcat Server via the installer, you can choose Start Tcat Server and Stop Tcat Server from the Tcat Server 6 group in the Windows Start menu.

To start the administration console, see below.

Additional Options on Linux

  • If you installed as a non-root user via the installer, you can use the graphical desktop applications menu to start, stop, or restart the server.

  • If you installed as root via the installer, you can use the init script:


           
        
1
service tcat6 start
  • If the service command isn’t available, use the following command instead:


           
        
1
/etc/init.d/tcat6 start
  • If you installed using the ZIP file instead of the installer and you have root privileges, follow the below instructions to complete the installation.

Starting and Stopping on Solaris 10 and 11

By default, Tcat Server automatically starts after installation on Solaris 10 and newer, as part of the Solaris Service Management Framework (SMF). Or, without using SMF, you may also directly invoke Tcat Server’s init script, named “tcat6”. You may invoke the tcat6 script in Tcat’s bin/ directory, or in the path /etc/init.d/tcat6 if you installed Tcat with root privileges. By default you should use SMF, but if you have insufficient permissions to use SMF, then the tcat6 init script works. For any single Tcat Server installation, you should choose to invoke either SMF or the tcat6 init script, not both.

Using SMF, you may query the service to inspect its current state like this:


          
       
1
sudo svcs -l tcat6

Or, if you’re not using SMF, you may query Tcat’s status like this:


          
       
1
/opt/TcatServer6/bin/tcat6 status

To stop Tcat Server, disable its SMF service:


          
       
1
sudo svcadm disable tcat6

Or, if you’re not using SMF, you may stop Tcat Server like this:


          
       
1
/opt/TcatServer6/bin/tcat6 stop

To start Tcat Server from a disabled state, run:


          
       
1
sudo svcadm enable tcat6

Or, if you’re not using SMF, you may start Tcat Server like this:


          
       
1
/opt/TcatServer6/bin/tcat6 start

You can also restart the server via SMF like this:


          
       
1
sudo svcadm restart tcat6

Or, if you’re not using SMF, you may restart Tcat Server like this:


          
       
1
/opt/TcatServer6/bin/tcat6 restart

Additional Options on Solaris

  • If your shell user does not have root permissions when you run the installer, the installer cannot add a tomcat shell user, nor can the installer install the Tcat Server SMF service. This is okay, and is a fully supported use case on Solaris. The user you use to run the Tcat installer is the user that the Tcat JVM runs as, and you should start|stop|restart Tcat Server on the command line via the tcat6 init script as described in the Starting and Stopping on Solaris 10 and 11 section above.

  • Installing Tcat Server inside a Solaris zone is also supported. The installer is unaware it is being installed in a non-global zone and the installation works the same as if you are installing it in the global zone. If you have root privileges in a zone, but the zone does not allow you to use SMF, then the installer may be unable to install the SMF service, but the installation will not fail – it succeeds and completes the installation without the SMF service. You can operate Tcat Server without SMF on the command line via the tcat6 init script as described in the Starting and Stopping on Solaris 10 and 11 section above. By default, Solaris 10 and 11 allow SMF to be used as root inside non-global zones. If you do not have root privileges in your non-global zone, installing Tcat inside this zone is the same as installing Tcat in the global zone without root privileges.

  • If you installed as root via the installer, you can invoke the init script for start|stop|restart|status:


           
        
1
/etc/init.d/tcat6 status

Installing Tcat Server via the Zip File on Linux

Here are the steps for installing Tcat Server on a Linux distribution from the zip file:

  1. sudo -s

  2. cd /opt

  3. unzip TcatServer-6.4.3.zip

    
                  
               
    1
    
    # export TCAT_HOME=/opt/TcatServer6
  4. If you wish to install Tcat Server into a different file system location, the recommended way to do that is using the automated installer. Try installing it into /opt/TcatServer6 first.

    
                  
               
    1
    2
    
    # groupadd tomcat
    # useradd -c "Tcat JVM user" -g tomcat -s /bin/bash -r -M -d $TCAT_HOME/temp tomcat

    If the 'tomcat' user already exists, do this instead:

    
                  
               
    1
    2
    
    # finger tomcat > ~/tomcat-user-settings.txt
    # usermod -s /bin/bash -d $TCAT_HOME/temp tomcat
  5. Either way, continue:

    
                  
               
    1
    2
    3
    4
    5
    6
    7
    
    # ln -s $TCAT_HOME/conf/Catalina/localhost/tcat6-linux.sh /etc/init.d/tcat6
    # ln -s $TCAT_HOME/conf/Catalina/localhost/tcat6-linux.sh $TCAT_HOME/bin/tcat6
    # ln -s $TCAT_HOME/conf/Catalina/localhost/tcat6-linux.sh $TCAT_HOME/conf/Catalina/localhost/tcat6
    # chmod 770 $TCAT_HOME/conf/Catalina/localhost/*.sh
    # chmod 660 $TCAT_HOME/conf/Catalina/localhost/*.conf
    # cp $TCAT_HOME/conf/Catalina/localhost/tcat-env-linux.conf $TCAT_HOME/conf/Catalina/localhost/tcat-env.conf
    # chown -R tomcat:tomcat $TCAT_HOME
  6. On Red Hat, CentOS, and Fedora Linux distributions, use the chkconfig command to make Tcat start upon a reboot:

    
                  
               
    1
    
    # chkconfig tcat6 on

    On other Linux distributions, such as Debian and Ubuntu, you can probably do the same thing this way:

    
                  
               
    1
    
    # update-rc.d tcat6 defaults
  7. Edit your Tcat Server’s environment file to set the value of JAVA_HOME to point to your Java JDK:

    
                  
               
    1
    
    $TCAT_HOME/conf/Catalina/localhost/tcat-env.conf

    If you do not have a JDK, but instead a JRE, set the value of JRE_HOME instead of JAVA_HOME. Make sure you set only one of these environment variables, not both.

  8. Start Tcat Server, like this:

    
                  
               
    1
    
    # service tcat6 start

    Or:

    
                  
               
    1
    
    # /etc/init.d/tcat6 start

To start the administration console, see Starting the Administration Console.

Starting and Stopping on Mac OS X

Navigate to the Tomcat bin directory and enter the following command at the terminal prompt:


          
       
1
startup.sh

To stop a Tcat Server instance, enter the following command:


          
       
1
shutdown.sh

Starting the Administration Console

To run the administration console, enter http://localhost:8080/console` in your web browser, replacing localhost:8080 with the correct server name and port where the console is deployed. You can now select and register one or more of the unregistered servers, adding them to server groups as needed. For more details, see Working with Servers.

Modifying JAVA_OPTS

There are several reasons to modify your JAVA_OPTS environment variable:

  • You want to enable JMX so that you can get more detailed information about connectors and server status, for example, -Dcom.sun.management.jmxremote

  • You need to increase your memory settings because you are installing all the components offered in the installer, , for example, -Xmx512M -XX:PermSize=64M -XX:MaxPermSize=128M

  • You need to modify the secure port, for example, -Dtcat.securePort=51444

After installing Tcat Server, you can modify JAVA_OPTS using the Tcat Server console, either by setting the options manually on each server by modifying the server’s environment variables or, if you have administrative privileges, by setting them in a server profile that you use across multiple Tcat Server instances.

Implementing Custom Restart Strategies

You can now specify custom restart strategies. These control how multiple servers are restarted. For instance, here is a script which specifies that there should be 30 seconds between restarting each server:


         
      
1
2
3
4
5
import com.mulesoft.common.server.restart.StaggeredRestartStrategy;
 
def serverManager = applicationContext.getBean("serverManager");
serverManager.setRestartStrategy(new StaggeredRestartStrategy(30000))
"Restart strategy installed"

Users can also specify custom restart strategies. For instance:


         
      
1
2
3
4
5
6
7
8
9
10
11
12
import com.mulesoft.common.server.restart.RestartStrategy;
 
def strategy = { serverManager, serverIds ->
  for (String id : serverIds) {
     println "Restarting ${id}"
     serverManager.restartServerNow(id);
   }
} as RestartStrategy
 
def serverManager = applicationContext.getBean("serverManager");
serverManager.setRestartStrategy(strategy)
"Restart strategy installed"

Uninstalling the Tcat Server

To uninstall the Tcat Server:

  • If you installed Tcat Server on Windows via the installer, choose Uninstall Tcat Server from the Windows Start menu.

  • If you manually installed Tcat Server and Tomcat in the same directory, and you want to delete both programs, simply delete the entire folder.

  • If you manually installed Tcat Server on an existing Tomcat installation, delete the console, agent webapps and their folders from the webapps directory.