Tomcat Server Setup

This describes the installation and configuration for a Tomcat server running on a Linux environment.  Windows installations can apply these configurations in a similar manner.  If you are unable to complete any of these steps because the command does not exist (e.g. service tomcat7 start, openssl dgst -md5 tomcat.tar.zip) then please contact SysAdmin for assistance.

tomcat user:

1. Make sure a user, tomcat, has been created with no privileges, no shell. (e.g. tomcat:x:506:99::/home/tomcat:/sbin/nologin).  If you are unsure how to do this please contact SysAdmin for assistance (e.g. sudo useradd -M -s /usr/bin/nologin -g nobody tomcat).
   
   

System configuration:
The following instructions configure various server components to work in conjunction with the Tomcat server and Java.  Within you find instructions on best practice for installing init.d script for Tomcat and how to create both $CATALINA_HOME and $JAVA_HOME for all users.

$CATALINA_HOME

1. • If an entry for catalina.sh does not already exist in /etc/profile.d/catalina.sh then you will need to create one; sudo vi /etc/profile.d/catalina.sh
     In this this file put the following line:
          export $CATALINA_HOME=/opt/apache-tomcat/current
     If the file already exists be sure it has the above entry.

$JAVA_HOME

• • If an entry for java.sh does not already exist in /etc/profile.d/java.sh then you will need to create one;  sudo vi /etc/profile.d/java.sh
    In this file put the following line:
    export $JAVA_HOME=/opt/java/current
    If the file already exists be sure it has the above entry.

/etc/init.d/tomcat7
The following configuration is the script that will start/stop/restart the Tomcat server both from the command line and executed when the system is restarted.  From the command line usually executed by calling - sudo service tomcat7 stop/start/restart  
In both cases the Tomcat server will be started to run with the permissions of the tomcat user.

• • If an entry for tomcat7 does not exist in /etc/init.d/tomcat7 then you will need to create one.  Attached to this issue is a file, initd-tomcat7.  Open the file and copy the contents into sudo vi /etc/init.d/tomcat7.  Save the file (e.g. :wq).
    If an entry for tomcat7 already exists be sure it contains a similar if not identical code as the attached file otherwise the Tomcat server may not be correctly started. 
  • Finally be sure the the script will be executed upon startup run the following command  sudo chkconfig /etc/init.d/tomcat7

Tomcat installation/update:

1. If  the server does not already have a directory, /opt/apache-tomcat, then create one (sudo mkdir /opt/apache-tomcat) and download the tomcat installation to this directory. Be sure to check the sha1 or md5 hash on the download site is the same as for the downloaded tomcat file (e.g. openssl dgst -md5 apache-tomcat-7.0.xx.zip).
2. Untar the tomcat distribution and delete the tar file (sudo tar cxf apache-tomcat-7.0.xx.tar.zip).
3. If the directory, /opt/apache-tomcat, did not exist create a "current" symlink to the new tomcat server directory (e.g. sudo ln -s apache-tomcat-7.0.xx current). If the directory, /opt/apache-tomcat, did exist and the link, current, was already there then you will need to sudo unlink current before linking it again.  NOTE: The reason for symlinking the directory is so any references to the current tomcat server (e.g. $CATALINA_HOME, /etc/init.d/tomcat7...) do not have to be updated.  This simplifies maintenance.
4. This concludes the steps necessary to install or update the version of Tomcat. Please see Tomcat configuration for steps required to configure Tomcat.

Tomcat configuration:
The following instructions configure various parts of the Tomcat server.  It is recommended that all configurations are applied.

Tomcat should always be started by the tomcat user and never as root or another user. Please see the attached tomcat7 script for an example of the script that should be in /etc/init.d/

the Tomcat as user tomcat. Once /etc/init.d/tomcat7 is in place
chkconfig /etc/init.d/tomcat7 can be run (sudo) so that the Tomcat
application is started on reboot. In addition sudo service tomcat7 start/stop/restart
is used to manually run Tomcat.

3) To enforce running Tomcat only as tomcat user add the following to $CATALINA_HOME/bin/catalina.sh

# Detect whether the correct user, tomcat, is running the script
if [ "$(whoami)" != "tomcat" ] ; then
echo ""
echo "Tomcat should ONLY be run by user tomcat !!!!!"
echo ""
exit 1
fi

This will ensure only tomcat can start Tomcat server. Please see $CATALINA_HOME/bin/catalina.sh
for more information.

4) Make sure all directories and files in $CATALINA_HOME are owned by tomcat:tomcat

5) An effort has been made to place versions of Tomcat in /usr/src/tomcat. A link, current, is used
to point to the version indicated by $CATALINA_HOME. This facilitates upgrading Tomcat so that
only the link needs to be changed and no changes has to be made to /etc/profile.d/catalina.sh
The same applies to java versions installed. On this machine all Java versions are placed in /usr/src/jvm
and a link, current, points to the version used by the environment variable $JAVA_HOME which again
is set for all users in /etc/profile.d/java.sh.
Your application of this concept may vary but by putting it into practice will make upgrading
versions of Tomcat and Java far less painful.

6) Create global environment variables for $CATALINA_HOME and $JAVA_HOME as described on this platform
in /etc/profile.d/catalina.sh , java.sh

7) JMX is a service we use to monitor the health of Tomcat while it is running. Changes need to be made to
$CATALINA_HOME/conf/server.xml and $CATALINA_HOME/conf/setenv.sh.
The following directive needs to be added to server.xml - it can be placed with the other listeners.

<Listener className="org.apache.catalina.mbeans.JmxRemoteLifecycleListener"
rmiRegistryPortPlatform="9090" rmiServerPortPlatform="9091" />

This will start the JMX server on port 9090 and the listenback on 9091. In order for this to work an additional library needs to be installed in $CATALINA_HOME/lib , catalina-jmx-remote.jar. Either make a
copy of the one in this TC or download the approprate version from Tomcat downloads /extras from Apache.

In addition the JMX service needs to be made available. This is done in the setenv.sh which is located in
$CATALINA_HOME/conf. This file is not included in the Tomcat download but is a file Tomcat will read if it
is available on startup. Copy the entries there to make the JMX service available. You will see it makes
reference to the $CATALINA_HOME/conf/jmxremote.access and ...jmxremote.password files. These files restrict
access to the JMX services and should be self-explanatory. Modify as needed but pay attention to the file
permissions in particular for jmxremote.password.
Once this has been completed you should be able to access JMX through jConsole or VisualVM ...etc.

8) External configuration files and shared jars are kept in $CATALINA_HOME/shared/classes and ...lib
respectively. These directories need to be made (chown tomcat:tomcat) and configured to be used by
the common classloader. This is done by appending the following to the common configuration in
$CATALINA_HOME/conf/catalina.properties

,${catalina.home}/shared/classes,${catalina.home}/shared/lib/*.jar

9) In order to use log4j as the catalina logger the log4j jar needs to be included in $CATALINA_HOME/lib as
well as log4j.properties. Open $CATALINA_HOME/lib/log4j.properties to view the current settings.
Additionally tomcat-juli.jar and tomcat-juli-adapters.jar needs to be downloaded from
Apache Tomcat /extras and installed in $CATALINA_HOME/bin, $CATALINA_HOME/lib respectively.
More information at http://tomcat.apache.org/tomcat-7.0-doc/logging.html#Using_Log4j