topics/tomcat/generalInstallAdvice/sharedInstall.txt
P. Conrad for CISC474 01/07/2006
This file describes how to run multiple instances of Tomcat
from a single install.
What do you mean by "multiple instances of Tomcat from a single install"?
==============================================================
An example probably makes this more clear.
For example, on strauss.udel.edu, Tomcat is installed in
/www/htdocs/CIS/software/dist/apache-tomcat-5.5.12
If you want to run your own tomcat server on strauss, you don't have
to download tomcat yourself; you can use this installation.
However, you still have to do some work yourself, because by default,
the configuration files for Tomcat live inside this directory structure,
and you don't have write access to these files.
What you need is your own set of configuration files, and way to direct
Tomcat to use _those_ configuration files, while using the
directory /www/htdocs/CIS/software/dist/apache-tomcat-5.5.12 for anything
that can be shared.
This document describes how to do that.
Important environment variables: CATALINA_BASE vs. CATALINA_HOME
================================================================
The way to make a shared install work is to separate two environments:
CATALINA_BASE your own personal configuration files
CATALINA_HOME the shared directory
CATALINA_BASE points to a directory, e.g. a subdirectory "tomcat" under
your home directory, where you make configuration changes and deploy your
webapps. You should have read/write access to these files.
CATALINA_HOME points to the place where the shared installation files live
(you have "read only" access to these files.).
In addition, another environment variable is helpful to define:
CATALINA_PID a file where the process id of your tomcat server is stored
An example will illustrate how to make this work.
Example setup
=============
For example, suppose your home directory on strauss is
/home/usra/98/76543
You might do the following:
setenv CATALINA_BASE /home/usra/98/76543/tomcat
setenv CATALINA_PID $CATALINA_BASE/http.pid
setenv CATALINA_HOME /www/htdocs/CIS/software/dist/apache-tomcat-5.5.12
You should be able to use $HOME to stand for your home directory, i.e.
setenv CATALINA_BASE $HOME/tomcat
setenv CATALINA_PID $CATALINA_BASE/http.pid
setenv CATALINA_HOME /www/htdocs/CIS/software/dist/apache-tomcat-5.5.12
For example, what I put in my .localenv is:
mkdir -p $HOME/tomcat
if -d $HOME/tomcat then
setenv CATALINA_BASE $HOME/tomcat
setenv CATALINA_PID $CATALINA_BASE/http.pid
if -d /www/htdocs/CIS/software/dist/apache-tomcat-5.5.12 then
setenv CATALINA_HOME /www/htdocs/CIS/software/dist/apache-tomcat-5.5.12
endif
endif
One time setup commands
=======================
Then to set things up, you'd do:
> mkdir -p $CATALINA_BASE
> cp -r $CATALINA_HOME/conf $CATALINA_BASE
> cd $CATALINA_BASE
> mkdir -p logs temp webapps work shared/lib shared/classes
Now:
$CATALINA_BASE/webapps is where you put your webapps
$CATALINA_BASE/conf/server.xml is where you configure _your_ server
One time configuration
======================
Some things you need to change in $CATALINA_BASE/conf/server.xml
(1) Change the shutdown port
A Tomcat instance has a port number on which it listens for shutdown
requests. You need to change 8005 to some other number that you've
been assigned, or that you choose arbitrarily.
Suppose you pick 8101. To be sure that number isn't already in use,
do the command "netstat -an | grep 8101" and make sure that 8101 isn't
already in the LISTEN state.
(2) Change the port on which the HTTP service is listening.
By default, Tomcat listens for connections on port 8080.
That means, you'll use a URL such as the following to connect to
your server:
http://strauss.udel.edu:8080
The place in the server.xml file that make this work is the following
XML element:
You need to choose a different port (see the previous item about
choosing a port not already in use). Change 8080 to whatever
port you decide to use (e.g. 8180).
(3) If you are using SSL to deploy an https:// type service, also
change the port 8443.
By default, the server.xml file has the SSL Connector commented out.
Note for example, the use of the XML comment brackets:
around the Connector element below:
However, if you "uncomment this" (and note that this is not necessarily
the _only_ thing you have to do to enable SSL and the https:// thing to work)
you'll need to change port 8443 to some other port.
If you want the example webapps to be under your tomcat directory, you
need to copy them in. However, be warned: they take up 8.2MB of space!
cp -r $CATALINA_HOME/webapps/* $CATALINA_BASE/webapps
If you don't do this, when you to to http://strauss.udel.edu:8180
(or whatever _your_ port is) you'll just see a blank screen (unless you
deployed some webapps of your own.)
Starting and stopping the server
================================
Provided you've set the environment variables CATALINA_HOME,
CATALINA_BASE and CATALINA_PID correctly, to start and stop
the server, you can still use the scripts from the shared install.
Startup:
$CATALINA_HOME/bin/startup.sh
Shutdown:
$CATALINA_HOME/bin/shutdown.sh
If these don't work, check that you followed ALL of the above
steps corrrectly (including avoiding port number conflicts with
other users on your system.)
What you need to do to make this work on the ECL machines,
e.g. porsche.cis.udel.edu and the clients of porsche.cis.udel.edu
=================================================================
The steps are very similar to those listed above for strauss.udel.edu.
Here are some differences:
(1) Instead of a .localenv, on the ECL machines you'll directly
edit your .cshrc file (or the bash equivalent)
(2) The location of CATALINA_HOME is different.
Here for example, are commands you might use in your .cshrc
on porsche if you use tcsh as your shell:
if -d /porsche/cisc474/tomcat/ then
setenv CATALINA_HOME /porsche/cisc474/tomcat
endif
if -d $HOME/tomcat then
setenv CATALINA_BASE $HOME/tomcat
endif
(3) You have been assigned a specific client of porsche.cis.udel.edu on which
to run your Tomcat server, and three port numbers to use with that server.
That table can be found at:
http://www.udel.edu/CIS/474/pconrad/06S/info/portsAndAccounts.html
or at the link "ports and accounts" on the main CISC474 web page.
For example, andersen should run his her server on subaru,
using ports 8001, 8101, and 8201.
That means you'll need to ssh into strauss.udel.edu first, then
ssh from there into porsche.cis.udel.edu, and then ssh into, for example,
subaru.
This is necessary because direct connections into porsche.cis.udel.edu
are only permitted from certain systems (for example strauss), and connections
into the clients of porsche are only permitted from porsche.
You'll use the commands below to set up your tomcat CATALINA_BASE
directory (identical to the ones used to set up your server on strauss).
(These commands can be run on porsche.cis.udel.edu OR on the client
machine.)
mkdir -p $CATALINA_BASE
cp -r $CATALINA_HOME/conf $CATALINA_BASE
cd $CATALINA_BASE
mkdir -p logs temp webapps work shared/lib shared/classes
But then, you'll edit the file $CATALINA_BASE/conf/server.xml as
follows:
(3a) Change the shutdown port
to the first port on your list, e.g if your list is 8001, 8101, 8201,
change this line to:
(3b) Change the port on which the HTTP service is listening
to the second port in your list. e.g if your list is 8001, 8101, 8201,
change this line from:
/dev/null 2> /dev/null
# now test the exit status of that command
ERROR_STATUS=$?
if [ $ERROR_STATUS -ne 0 ]
then
hostname
echo server is down\; curl status code $ERROR_STATUS
$CATALINA_HOME/bin/startup.sh
# else
# hostname
# echo server on $URL is up
fi
The "else...echo server is up" command is commented out so that we don't get
email every time the script runs as a cron job and we find out that
the server is indeed up. However, it is nice to have this line of
output when running the script interactively, or when first testing
the cron job.
The following line in the crontab will run the script at 28 minutes
after the hour once per hour.
28 * * * * /usa/pconrad/cisc474/monitorTomcat.sh
Note that the crontab must be run on the machine where you want
to restart the server (e.g. on suzuki not on porsche)!
That's why we have to use the URL http://localhost:8106 rather than
http://porsche.cis.udel.edu:8106 ... as it turns out, you can't
connect to porsche.cis.udel.edu (per se) from the clients of porsche.