1.0 Introduction<\/p>\n
Java servlets are a powerful tool for building websites and web based applications. One skill that every Java web developer should have is the ability to install and configure the Tomcat servlet engine. Many thanks to the Apache Software Foundation<\/a> for providing this mature, stable, open source software. It was recently voted the Best Application Server of 2003<\/a> by InfoWorld readers.<\/p>\n This article discusses how to integrate Tomcat with the Apache web server on Red Hat Linux 9 or Red Hat Enterprise Linux 3. The goal is to provide a simple, stable configuration that will allow users to gain confidence using Tomcat in a development environment. Setting up a production Tomcat server is outside the scope of this article.<\/p>\n Please note the following conventions:<\/p>\n I chose to install Apache using the Red Hat RPM. Using the RPM instead of compiling Apache from source simplifies system administration in the following ways:<\/p>\n I recommend using the Red Hat up2date command line utility to install Red Hat RPMs. It eliminates a multitude of headaches by ensuring the software you install is the correct version and you have the right dependencies installed on your system.<\/p>\n Install the following Red Hat RPMs if they are not already installed:<\/p>\n To install these packages using up2date, make sure you are connected to the Internet, and enter the following:<\/p>\n <\/p>\n You should now be able to start\/stop\/restart Apache as follows:<\/p>\n <\/p>\n Verify that Apache is working by starting Apache and typing http:\/\/localhost\/ into your browser. You should see the default Apache install page with links to documentation.<\/p>\n The only requirements to run Tomcat are that a Java Development Kit (JDK), also called a Java Software Development Kit (SDK), be installed and the JAVA_HOME environment variable be set.<\/p>\n I chose to install Sun\u2019s Java 2 Platform, Standard Edition, which can be downloaded from http:\/\/java.sun.com\/j2se\/)<\/a>. I chose the J2SE v1.4.2 SDK Linux self-extracting binary file.<\/p>\n Change to the directory where you downloaded the SDK and make the self-extracting binary executable:<\/p>\n <\/p>\n Run the self-extracting binary:<\/p>\n <\/p>\n There should now be a directory called j2sdk1.4.2 in the download directory. Move the SDK directory to where you want it to be installed. I chose to install it in \/usr\/java. Create \/usr\/java if it doesn\u2019t exist. Here is the command I used from inside the download directory:<\/p>\n <\/p>\n Set the JAVA_HOME environment variable, by modifying \/etc\/profile so it includes the following:<\/p>\n <\/p>\n \/etc\/profile is run at startup and when a user logs into the system, so you will need to log out and log back in for JAVA_HOME to be defined.<\/p>\n <\/p>\n Check to make sure JAVA_HOME is defined correctly using the command below. You should see the path to your Java SDK.<\/p>\n <\/p>\n You will install and configure Tomcat as root; however, you should create a dedicated group and user account for Tomcat to run under as follows:<\/p>\n <\/p>\n Download the latest release binary build from http:\/\/www.apache.org\/dist\/jakarta\/tomcat-5\/<\/a>. Since Tomcat runs directly on top of a standard JDK, I cannot think of any reason to building it from source. There are a number of different download formats. I chose the gnu zipped tar file (jakarta-tomcat-5.0.28.tar.gz).<\/p>\n Unzip Tomcat by issuing the following command from your download directory:<\/p>\n <\/p>\n This will create a directory called jakarta-tomcat-5.0.28. Move this directory to wherever you would like to install Tomcat. I chose \/usr\/local. Here is the command I issued from inside the download directory:<\/p>\n <\/p>\n The directory where Tomcat is installed is referred to as CATALINA_HOME in the Tomcat documentation. In this installation CATALINA_HOME=\/usr\/local\/jakarta-tomcat-5.0.28.<\/p>\n I recommend setting up a symbolic link to point to your current Tomcat version. This will save you from having to make changes to startup and shutdown scripts each time you upgrade Tomcat. It also allows you to keep several versions of Tomcat on your system and easily switch amongst them. Here is the command I issued from inside \/usr\/local to create a symbolic link called \/usr\/local\/jakarta-tomcat that points to \/usr\/local\/jakarta-tomcat-5.0.28:<\/p>\n <\/p>\n Change the group and owner of the \/usr\/local\/jakarta-tomcat and \/usr\/local\/jakarta-tomcat-5.0.28 directories to tomcat:<\/p>\n <\/p>\n It is not necessary to set the CATALINA_HOME environment variable. Tomcat is smart enough to figure out CATALINA_HOME on its own.<\/p>\n You should now be able to start and stop Tomcat from the CATALINA_HOME\/bin directory by typing .\/startup.sh and .\/shutdown.sh respectively. Test that Tomcat is working by starting it and typing http:\/\/localhost:8080 into your browser. You should see the Tomcat welcome page with links to documentation and sample code. Verify Tomcat is working by running some of the examples.<\/p>\n At this point, Apache and Tomcat should be working separately in standalone mode. You can run Tomcat in standalone mode as an alternative to Apache. In fact, in some cases, it is said that Tomcat standalone is faster than serving static content from Apache and dynamic content from Tomcat. However, there are the following compelling reasons to use Apache as the front end:<\/p>\n The increased functionality obtained by using Apache on the front end can outweigh the effort required to install and configure a connector.<\/p>\n Development on the mod_jk2 connector was discontinued on 11\/15\/2004; therefore, you no longer have to decide between the mod_jk and mod_jk2 connectors. Use the mod_jk connector. It has been around a long while and is very stable.<\/p>\n The mod_jk connector is the communication link between Apache and Tomcat. It listens on a defined port for requests from Apache and forwards those requests to Tomcat.<\/p>\n Install the following Red Hat RPMs if they are not already installed:<\/p>\n Download the jk connector source from http:\/\/www.apache.org\/dist\/jakarta\/tomcat-connectors\/jk\/<\/a>. I used jakarta-tomcat-connectors-1.2.8-src.tar.gz.<\/p>\n Unzip the contents of the file into your download directory as follows:<\/p>\n <\/p>\n This will create a folder called jakarta-tomcat-connectors-1.2.8-src. Move this folder to wherever you store source files on your system. I chose \/usr\/src. Here is the command I issued from inside the download directory:<\/p>\n <\/p>\n I refer to the folder where the connector source is installed as CONN_SRC_HOME. In my case CONN_SRC_HOME = \/usr\/src\/jakarta-tomcat-connectors-1.2.8-src.<\/p>\n Change to directory CONN_SRC_HOME\/jk\/native and run the buildconf.sh script as follows:<\/p>\n <\/p>\n This will create the CONN_SRC_HOME\/jk\/native\/configure file. Run the configure script with the path to the apxs file on your system. If you installed Apache using the Red Hat RPM, apxs should be located at \/usr\/sbin\/apxs.<\/p>\n <\/p>\n Build mod_jk with the following command:<\/p>\n <\/p>\n If you see missing object errors, try this alternate command:<\/p>\n <\/p>\n If all went well, the mod_jk.so file was successfully created. Manually copy it to Apache\u2019s shared object files directory:<\/p>\n <\/p>\n Both Apache and Tomcat application files will be installed under the \/home\/tomcat\/webapps directory. This setup will allow you to easily upgrade Tomcat and back up your application files.<\/p>\n Create your application directories as follows:<\/p>\n <\/p>\n Set directory permissions as follows:<\/p>\n <\/p>\n The workers.properties file contains information so mod_jk can connect to the Tomcat worker processes.<\/p>\n Place the following workers.properties file in the \/etc\/httpd\/conf directory:<\/p>\n <\/p>\n Notes<\/p>\n The CATALINA_HOME\/conf\/server.xml file contains Tomcat server configuration information. The default server.xml is great for verifying that Tomcat works in standalone mode and for viewing the examples that come with the application, but it contains so much information that it can be confusing. I recommend saving it for future reference and creating a new server.xml.<\/p>\n Save the default server.xml as follows:<\/p>\n <\/p>\n Copy the following into a new server.xml file:<\/p>\n <\/p>\n If you do keep the default server.xml, make sure you comment out any other connectors besides mod_jk that are listening on port 8009. The default file comes with the Coyote\/JK2 connector enabled for the Tomcat-Standalone service. This will conflict with the mod_jk connector in your Tomcat-Apache service. You should comment this connector out. It isn\u2019t needed when you connect directly to Tomcat in standalone mode (port 8080), so I\u2019m not sure why this connector is enabled by default.<\/p>\n The Connector address defines the interface that Tomcat will listen on for mod_jk requests from Apache. In my configuration, Apache and Tomcat reside on the same box, so I have set the address to the loopback address. The default is for Tomcat to listen on all interfaces, so restricting it to the loopback interface improves security.<\/p>\n The Server shutdown property is the text string that is sent over a socket connection to stop Tomcat. The default value is \u201cSHUTDOWN\u201d. The shutdown port is always on the loopback interface, which provides host-level protection. However, there is the possibility that the host could be compromised and someone could send the command SHUTDOWN to all ports and knock Tomcat offline. To prevent this, replace the default value with one that is difficult to guess. Do not use the example string above.<\/strong> Create your own by feeding random bytes into md5sum as follows:<\/p>\n <\/p>\n Change the permissions on server.xml to prevent unprivileged users from reading the shutdown string:<\/p>\n <\/p>\n It is recommended that contexts be defined in separate files, not in server.xml. The context configuration directory has the same name as the Engine in server.xml.<\/p>\n Create the context configuration directory as follows:<\/p>\n <\/p>\n The host context configuration directory has the same name as the corresponding Host in server.xml.<\/p>\n Create the context configuration directory for your domain as follows:<\/p>\n <\/p>\n Create the context configuration file as follows:<\/p>\n <\/p>\n Copy the following text into {YOUR_APPLICATION}.xml:<\/p>\n <\/p>\n Setting the Context reloadable property to true tells Tomcat to automatically load new and changed application class files found in \/WEB-INF\/classes and \/WEB-INF\/lib. This feature is very useful during development. However, it is recommended to set reloadable to false in production environments<\/strong> because monitoring class file changes requires significant server resources.<\/p>\n Download the latest log4j<\/a> and install log4j.jar in CATALINA_HOME\/common\/lib.<\/p>\n\n
2.0 Installing Apache<\/h2>\n
\n
\n
up2date -i httpd httpd-devel<\/pre>\n
service httpd start\r\nservice httpd stop\r\nservice httpd restart<\/pre>\n
3.0 Installing Tomcat<\/h2>\n
3.1 Java SDK<\/h3>\n
chmod +x j2sdk-1_4_2-linux-i586.bin<\/pre>\n
.\/j2sdk-1_4_2-linux-i586.bin<\/pre>\n
mv j2sdk1.4.2 \/usr\/java<\/pre>\n
JAVA_HOME=\"\/usr\/java\/j2sdk1.4.2\"\r\nexport JAVA_HOME<\/pre>\n
exit\r\nsu -<\/pre>\n
echo $JAVA_HOME<\/pre>\n
3.2 Tomcat Account<\/h3>\n
groupadd tomcat\r\nuseradd -g tomcat tomcat<\/pre>\n
3.3 Download Tomcat<\/h3>\n
3.4 Tomcat Standalone<\/h3>\n
tar xvzf jakarta-tomcat-5.0.28.tar.gz<\/pre>\n
mv jakarta-tomcat-5.0.28 \/usr\/local\/<\/pre>\n
ln -s jakarta-tomcat-5.0.28 jakarta-tomcat<\/pre>\n
chown tomcat.tomcat \/usr\/local\/jakarta-tomcat\r\nchown -R tomcat.tomcat \/usr\/local\/jakarta-tomcat-5.0.28<\/pre>\n
4.0 Installing the Connector<\/h2>\n
4.1 Connector Benefits<\/h3>\n
\n
4.2 Selecting a Connector<\/h3>\n
4.3 Building the mod_jk Connector<\/h3>\n
\n
tar xvzf jakarta-tomcat-connectors-1.2.8-src.tar.gz<\/pre>\n
mv jakarta-tomcat-connectors-1.2.8-src \/usr\/src<\/pre>\n
.\/buildconf.sh<\/pre>\n
.\/configure --with-apxs=\/usr\/sbin\/apxs<\/pre>\n
make<\/pre>\n
make LIBTOOL=\/etc\/httpd\/build\/libtool<\/pre>\n
cp CONN_SRC_HOME\/jk\/native\/apache-2.0\/mod_jk.so \/etc\/httpd\/modules<\/pre>\n
5.0 Creating the Application Directories<\/h2>\n
mkdir \/home\/tomcat\/webapps\r\nmkdir \/home\/tomcat\/webapps\/{YOUR_DOMAIN}\r\nmkdir \/home\/tomcat\/webapps\/{YOUR_DOMAIN}\/logs\r\nmkdir \/home\/tomcat\/webapps\/{YOUR_DOMAIN}\/{YOUR_APPLICATION}\r\nmkdir \/home\/tomcat\/webapps\/{YOUR_DOMAIN}\/{YOUR_APPLICATION}\/WEB-INF\r\nmkdir \/home\/tomcat\/webapps\/{YOUR_DOMAIN}\/{YOUR_APPLICATION}\/WEB-INF\/classes<\/pre>\nchmod 755 \/home\/tomcat\/webapps\r\nchmod 755 \/home\/tomcat\/webapps\/{YOUR_DOMAIN}\r\nchmod 755 \/home\/tomcat\/webapps\/{YOUR_DOMAIN}\/{YOUR_APPLICATION}<\/pre>\n6.0 Configuring Tomcat<\/h2>\n
6.1 workers.properties<\/h3>\n
# workers.properties - ajp13\r\n#\r\n# List workers\r\nworker.list=wrkr\r\n#\r\n# Define wrkr\r\nworker.wrkr.port=8009\r\nworker.wrkr.host=localhost\r\nworker.wrkr.type=ajp13\r\nworker.wrkr.cachesize=10\r\nworker.wrkr.cache_timeout=600\r\nworker.wrkr.socket_timeout=300<\/pre>\n
\n
6.2 server.xml<\/h3>\n
mv CATALINA_HOME\/conf\/server.xml CATALINA_HOME\/conf\/server.xml.orig<\/pre>\n
<Server port=\"8005\" shutdown=\"0fbb9aebcbfbef203eca71b6be367859\" debug=\"0\">\r\n\r\n\t<Service name=\"Tomcat-Apache\">\r\n\r\n\t\t<Connector address=\"127.0.0.1\"\r\n\t\t\tport=\"8009\"\r\n\t\t\tminProcessors=\"5\"\r\n\t\t\tmaxProcessors=\"75\"\r\n\t\t\tenableLookups=\"false\"\r\n\t\t\tprotocol=\"AJP\/1.3\"\r\n\t\t\tdebug=\"0\"\/>\r\n\r\n\t\t<Engine name=\"appserver\"\r\n\t\t\tdebug=\"0\"\r\n\t\t\tdefaultHost=\"{YOUR_DOMAIN}\">\r\n\r\n\t\t\t<Host name=\"{YOUR_DOMAIN}\"\r\n\t\t\t\tappBase=\"\/home\/tomcat\/webapps\"\r\n\t\t\t\tautoDeploy=\"false\"\r\n\t\t\t\tdeployOnStartup=\"false\"\r\n\t\t\t\tunpackWARs=\"false\"\r\n\t\t\t\tdeployXML=\"true\"\r\n\t\t\t\tdebug=\"0\"\/>\r\n\r\n\t\t<\/Engine>\r\n\r\n\t<\/Service>\r\n\r\n<\/Server><\/pre>\nhead -1024c \/dev\/random | md5sum<\/pre>\n
chmod 600 CATALINA_HOME\/conf\/server.xml<\/pre>\n
6.3 Configuring the Context<\/h3>\n
mkdir CATALINA_HOME\/conf\/appserver<\/pre>\n
mkdir CATALINA_HOME\/conf\/appserver\/{YOUR_DOMAIN}<\/pre>\ntouch CATALINA_HOME\/conf\/appserver\/{YOUR_DOMAIN}\/{YOUR_APPLICATION}.xml<\/pre>\n<Context path=\"\"\r\n\tdocBase=\"{YOUR_APPLICATION}\"\r\n\treloadable=\"true\"\r\n\tdebug=\"0\"\/><\/pre>\n6.4 log4j<\/h3>\n