Tomcat Server Setup

This describes the installation and configuration for a Tomcat server running on a Linux platform and how to download install/update the Java version. 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 tomcat8 start, openssl dgst -md5 tomcat.tar.zip) then please contact SysAdmin for assistance.

Whatever you do please read the FINAL STEPS at the bottom of the page.

tomcat user:

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 /sbin/nologin -g nobody tomcat).
Edit /etc/passwd, change /home/tomcat to /opt/apache-tomcat/current

Java installation/update:

If the server does not already have the directory /opt/java then create one (sudo mkdir /opt/java). change to this directory - cd /opt/java
Download the version of java appropriate for this version of linux (e.g. x86_64). The version of linux can be determined by running uname -a from the command line.

Oracle requires that you have accepted the license before you download the tar.gz file. This can be problematic for wget. Following is the command to run the download. Go to the Oracle Java download site, click on the accept license button, select the JDK version for this machine and copy the link. Use the "JDK Server" version if available. Replace the link below in the following command with the one you have copied:

sudo wget --no-cookies \
--no-check-certificate \
--header "Cookie: oraclelicense=accept-securebackup-cookie" \
"http://download.oracle.com/otn-pub/java/jdk/7u55-b13/jdk-7u55-linux-x64.tar.gz"

Once the file has completed downloading untar the java distribution and delete the tar file ( sudo tar zxvf jdk-7u55-linux-x64.tar.gz ).
If the directory, /opt/java, did not exist create a "current" symlink to the new java directory (e.g. sudo ln -s jdk-7u55-linux-x64 current). If the directory, /opt/java, 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 java installation (e.g. $JAVA_HOME, /etc/profile.d/java.sh...) do not have to be updated. This simplifies maintenance.
Remove any previous Java installation from the system. In Centos, get a list of packages:

rpm -qa | grep openjdk

sudo rpm -e [package-name]

At this point, if you do a java -version, you should get: -bash: /usr/bin/java: No such file or directory

System Configuration:
The following instructions configure various server components to work in conjunction with the Tomcat server and Java. Below you will 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

- 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.
- Once you open a new shell or login you will be able to test this configuration:
  echo $CATALINA_HOME should return /opt/apache-tomcat/<the directory you installed>

$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

export PATH=$JAVA_HOME/bin:$PATH

If the file already exists be sure it has the above entries.
Once you open a new shell or login you will be able to test this configuration:

echo $JAVA_HOME should return /opt/java/<the directory you installed> - and running java -version should return the version of Java you have installed.

NOTE: If you have installed java/components you may need to redirect the installed links (e.g. /etc/alternatives/java...) to point to /opt/java/current.

/etc/init.d/tomcat8
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 tomcat8 does not exist in /etc/init.d/tomcat8 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/tomcat8. Change all instances of tomcat7 to tomcat8 in this file. Save the file (e.g. :wq).
  If an entry for tomcat8 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 to be sure the the script will be executed upon startup run the following command sudo chkconfig /etc/init.d/tomcat8

Tomcat installation/update:

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. You can download Tomcat 8 from the Apache Tomcat site (http://tomcat.apache.org/) using wget (e.g. wget http://mirrors.advancedhosters.com/apache/tomcat/tomcat-8/SOMEVERSION/bin/apache-tomcat-SOMEVERSION.tar.gz)
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.tar.gz).
Untar the tomcat distribution and delete the tar file (sudo tar zxvf apache-tomcat-8.0.20.tar.gz).
If the directory, /opt/apache-tomcat/current, did not exist create a "current" symlink to the new tomcat server directory (e.g. sudo ln -s apache-tomcat-8.0.20 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/tomcat8...) do not have to be updated. This simplifies maintenance.
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.
The first task is to be sure tomcat is run with the permissions of the tomcat user. This is far more secure than running tomcat as root and will point out any misconfigurations that will certainly be found when your applications are deployed to a production environment. In order to complete the following configuration steps System configuration, Java installation/update and Tomcat installation/update need to be completed and you should have opened a new shell or logged in again to refresh your profile.

tomcat user enforcement

- To enforce running Tomcat only as tomcat user add the following to the top of $CATALINA_HOME/bin/catalina.sh after #!/bin/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 "try sudo service tomcat start"
  echo ""
  exit 1
  fi
- This will ensure even if someone tries to start Tomcat as a user other than tomcat (e.g. sudo bin/startup.sh) they will receive an error and instructions on how to correctly start the server.

tomcat server - reasonable defaults

- Following are some reasonable defaults to run Tomcat under. They include setting memory constraints, modest increase of PermGen so redeploying applications does not cause OutOfMemoryError PermGen space errors, Java GC and JMX file settings. We encourage use of JMX because it is a standard we increasingly use for runtime monitoring and configuration and many applications now depend on JMX to run correctly. Some of the settings will require editing to reflect your environment (e.g. ...jmx.rmi.server.hostname=192.168.1.xxx).
- The following settings also define paths for "endorsed" lib and bin directories. If you are unsure what these are for you probably don't need them but they should be configured in case they are needed.
- If your current $CATALINA_HOME/bin/setenv.sh does not have setenv.sh then you will need to create it - sudo vi $CATALINA_HOME/bin/setenv.sh This file is read by catalina.sh if it exists. Copy/save into this file the following lines changing those configuration items that are different for your system (e.g. 192.168.1.xxx)

CATALINA_OPTS="-Xms512m -Xmx1024m \
-XX:NewSize=256m -XX:MaxNewSize=256m \
-XX:+DisableExplicitGC -XX:+UseParallelGC \
-Dcom.sun.management.jmxremote.ssl=false \
-Dcom.sun.management.jmxremote.password.file=$CATALINA_HOME/conf/jmxremote.password \
-Dcom.sun.management.jmxremote.access.file=$CATALINA_HOME/conf/jmxremote.access"

export CATALINA_OPTS
export LD_LIBRARY_PATH=$CATALINA_HOME/endorsed/current/lib:$LD_LIBRARY_PATH
export PATH="$PATH:$CATALINA_HOME/endorsed/current/bin"

For JMX configuration:

CATALINA_OPTS="-Dcom.sun.management.jmxremote \
-Djava.rmi.server.hostname=HOSTNAME or IP \
-Xms512m -Xmx1024m \
-XX:NewSize=256m -XX:MaxNewSize=256m \
-XX:+DisableExplicitGC -XX:+UseParallelGC \
-Dcom.sun.management.jmxremote.ssl=false \
-Dcom.sun.management.jmxremote.password.file=$CATALINA_HOME/conf/jmxremote.password \
-Dcom.sun.management.jmxremote.access.file=$CATALINA_HOME/conf/jmxremote.access"

Tomcat Manager
In order to use the ..../manager/html interface to un/deploy/stop/start applications, GC and in broad terms see what is going on in the Tomcat server (in addition to JMX) you need to configure access to the url. This is done in the $CATALINA_HOME/conf/tomcat-users.xml file. The file has instructions and in the Apache documentation there is more elaboration. A starting point for basic but very insecure configuration can be copied from the above file and modified as needed.
If the server is to host a public IP and it is required that there is access to the Tomcat Manager then it is required that access be limited to the internal VPN. To do so include the following RemoteValveAddr code to the <Context> </Context> in the applications context.xml located in webapps/manager/META-INF and webapps/host-manager/META-INF.

JMX
JMX is a service we use to monitor the health of Tomcat while it is running as well as updates to runtime configuration. Changes need to be made to $CATALINA_HOME/conf/server.xml and $CATALINA_HOME/bin/setenv.sh. Please see tomcat server - reasonable defaults for setenv.sh changes.

- The following directive needs to be added to server.xml - place it 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 (change if needed).
- An additional library, catalina-jmx-remote.jar, needs to be downloaded from the Apache Tomcat Download Extras site (e.g. http://tomcat.apache.org/download-80.cgi) and placed in $CATALINA_HOME/lib. Try this command to download the required library: sudo wget http://www.gtlib.gatech.edu/pub/apache/tomcat/tomcat-8/v8.0.20/bin/extras/catalina-jmx-remote.jar
- Once these steps are completed and those of setenv.sh, JMX will be enabled.
- In order to access JMX two files need to be created in $CATALINA_HOME/conf They are jmxremote.access and jmxremote.password. Click on the attached files to copy the contents to the appropriate file contents to the respective file you create in $CATALINA_HOME/conf (e.g. sudo vi $CATALINA_HOME/conf/jmxremote.access ). Change the values in the files as appropriate.

External configuration and shared jars - shared/classes , shared/lib
External configuration files and shared jars are kept in $CATALINA_HOME/shared/classes and ...lib respectively. These directories need to be created and configured to be used by
the Tomcat common classloader.

- First create the directories - sudo mkdir -p $CATALINA_HOME/shared/classes - sudo mkdir $CATALINA_HOME/shared/lib
- Now configure the class loader by appending the following code to the line beginning with common.loader... in $CATALINA_HOME/conf/catalina.properties
  
  ,"${catalina.home}/shared/classes","${catalina.home}/shared/lib/*.jar","${catalina.base}/shared/classes","${catalina.base}/shared/lib/*.jar"
- Once completed properties files, resource bundles, SpringConfigurator.xml files and shared libraries (e.g. Junit.jar, mysql-connector-java-5.x.xxx.jar) ...etc. can be found on the classpath by any application.

LOG4J
In order to use log4j as the catalina logger instead of the default, java.util.logging, the log4j jar needs to be included in $CATALINA_HOME/lib with a log4j.properties file. Additionally, from the Apache Tomcat Extras files, tomcat-juli.jar and tomcat-juli-adapters.jar, need to be downloaded and installed.

- Download log4j v.1.2 or greater. (e.g. wget http://archive.apache.org/dist/logging/log4j/1.2.17/log4j-1.2.17-javadoc.jar ) be sure to check the md5 signature ( http://archive.apache.org/dist/logging/log4j/1.2.17/log4j-1.2.17-javadoc.jar.md5 )
- Install the log4j jar into $CATALINA_HOME/lib
- Create a log4j.xml file and put it in $CATALINA_HOME/lib ( sudo vi $CATALINA_HOME/lib/log4j.xml ).
- Download tomcat-juli.jar from Apache Tomcat Extras (wget http://mirror.reverse.net/pub/apache/tomcat/tomcat-7/v7.0.55/bin/extras/tomcat-juli.jar ) and install it in $CATALINA_HOME/bin where it will replace the existing file of the same name.
- Download tomcat-juli-adapters.jar from Apache Tomcat Extras (wget http://mirror.reverse.net/pub/apache/tomcat/tomcat-7/v7.0.55/bin/extras/tomcat-juli-adapters.jar ) and install it in $CATALINA_HOME/lib
- Starting/restarting Tomcat will use log4j for logging.

Enable HTTPS:

This configuration will guide you through the configuration of HTTPS on tomcat. These steps will create an individual keystore containing a single key that will be used by tomcat to create the secure connections.

The first step is to create the keystore:

sudo $JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA -keystore $CATALINA_HOME/conf/keystore

'tomcat' parameter specifies the name of the key we want to include in the keystore. Once this command is executed, the system will ask for some information regarding the keystore such as password (for the keystore and the key) and information about the Organization behind the keystore.

The result of this command is a keystore file created in $CATALINA_HOME/conf/keystore

To change the default expiration of the self-signed certificate, use the following command:

sudo $JAVA_HOME/bin/keytool -selfcert -v -alias tomcat -validity 3650 -keystore keystore

Note: In the above example, certificate is valid for the next 10 years.

The next step is to edit $CATALINA_HOME/conf/server.xml to configure and enable the HTTPS connector. Inside this file locate the following connector:

By default, the connector is not enabled (it is commented in the xml file). You need to enable it (uncomment it) and configure it in order to use the created keystore:

Make sure to use the same password you used when you created the keystore.

Restart tomcat and try to access it through HTTPS: http://localhost:8443/.

FINAL STEPS - REALLY IMPORTANT

Finally cd to $CATALINA_HOME and execute the following command - sudo chown -R tomcat:nobody ./
This will make the tomcat user owner for all files allowing for read/write access - otherwise the server will not start because it cannot log or read certain files.

Remember - have fun!