topics/tomcat/generalInstallAdvice/installingFromTarball.txt P. Conrad for CISC474 01/06/2006 This file contains a description of things you may run into when installing Tomcat from scratch on a system. Background needed ================= This document assumes you are familiar with: (1) the tar and gunzip utiltities, and what a tarball is (.tar.gz or .tgz) (2) what Tomcat is, and why you might want to install it. (3) basic Unix file manipulation (4) the wget command for retreiving files via http at the Unix command line (5) the scp command for doing secure file transfer at the Unix command line Steps ===== (1) Getting the tarball ======================= The website is http://tomcat.apache.org The tarball name will be something like: apache-tomcat-5.5.12.tar.gz Possible complications: (1a) If you are working on a system other than the one where your web browser is running (e.g. web browser on a PC, but you are ssh'd from that PC into a Unix system), a useful technique is to use "right click" to "copy link location", and then paste that into your shell window after the "wget" command, e.g.: > wget http://themirror.where.apache.lives.com/apache-tomcat-5.5.12.tar.gz If you don't have the wget command, then you'll have to download it to your PC and then copy it over with scp, for example. (2) Verifying integrity via PGP or MD5 ======================================= Since you are very likely going to get this file from a mirror site rather than directly from tomcat.apache.org, and also because of the possibility of various kinds of internet tomfoolery, you really ought to verify the file's integrity before proceeding. I'm only going to cover the md5sum technique, leaving discovery of the pgp technique as an exercise to the reader. Along with the file, there should be an md5 checksum. This is a number computed as a hash over the entire contents of the tar.gz file, e.g. On the page: http://tomcat.apache.org/download-55.cgi#5.5.12 See the link for md5: http://www.apache.org/dist/tomcat/tomcat-5/v5.5.12/bin/apache-tomcat-5.5.12.tar.gz.md5 This md5 file contains a single line of text: 4c51a16d86131ca7958273080efb473f If you run the command > md5sum apache-tomcat-5.5.12.tar.gz on the file you downloaded, you should get the exact same number as output. If you don't, you should delete the tarball, and start over. Possible complications (2a) (2) Next step: expand the tarball ================================= Of course, this is: gunzip apache-tomcat-5.5.12.tar.gz tar -xvf apache-tomcat-5.5.12.tar Or on a linux system, in one step: tar -xvzf apache-tomcat-5.5.12.tar.gz There are ways to do it on a non-linux system in one step via pipelining; I'll leave that as an exercise for you to discover. Things you might run into: ------------------------ (2a) If your version of tar is not the GNU version of tar, you might get a "checksum error". In that case, you need to either find gnu tar on your system and put it in your path earlier than the "other" version of tar, or download and install GNU tar on your system. A version of GNU tar is located on strauss in: /www/htdocs/CIS/software/gnu/bin Annoyingly, this version doesn't come with man pages. Documentation for gnu tar is available (1) via the web: http://www.gnu.org (1) on strauss via the "info" system (set INFOPATH env variable to: /www/htdocs/CIS/software/gnu/info:/www/htdocs/CIS/software/gnu/share/info and type "info") (3) Starting it up ================== Once you've unpacked the tarball, cd into the resulting directory and look at the file "RUNNING.txt". That will give you advice on what to do next. (3a) Things you might run into: Port numbers in use --------------------------------------------------- Note that the "generic" advice in this file, i.e. to type, on Unix: > ./bin/startup.sh or on Windows: > ./bin/startup.bat will only work if you already have JAVA_HOME pointing to a valid Java 5.0 JRE, and if port 8080 is available on your local host. To check whether that port is available on a Unix system, you can use: > netstat -an | grep 8080 > If you get back "nothing", then port 8080 is typically free. The following output, by contrast, shows port 8080 in use: > netstat -an | grep 8080 *.8080 *.* 0 0 49152 0 LISTEN > The output above shows that a socket is listening on port 8080. If you look at the full report (rather than just grep'ing for the lines containing 8080) you'll see that the socket is a TCP socket). The following output show a listening socket, and also an actual connection from IP address 68.82.69.104 (which happens to be my Comcast cable modem connection.) > netstat -an | grep 8080 *.8080 *.* 0 0 49152 0 LISTEN 128.175.13.74.8080 68.82.69.104.2432 33580 0 49232 0 ESTABLISHED > It is possible to get back output, but still have port 8080 free... for example, the following line contains 8080, but it is just a red herring; the number 48080 happens to contain 8080, but 8080 isn't in the port number fields (which in this case are 22 and 49219). > netstat -an | grep 8080 128.175.13.74.22 128.175.141.185.49219 65535 1943 48080 0 ESTABLISHED > When shutting down the server, you'll may temporarily see the following: > netstat -an | grep 8080 128.175.13.74.8080 68.82.69.104.2434 33487 0 48238 0 FIN_WAIT_2 128.175.13.74.8080 68.82.69.104.2435 33487 0 49232 0 FIN_WAIT_2 127.0.0.1.48974 127.0.0.1.8080 49152 0 49152 0 TIME_WAIT > This FIN_WAIT_2 and TIME_WAIT states show TCP connections that are in the process of being closed. It can take up to 2MSL seconds---that is, twice the maximum segment lifetime, typically between 30 seconds and 2 minutes---for a TCP connection to be closed. Consult a textbook on TCP/IP networking for more details if you are interested (or take the UD course CISC450!) For purposes of CISC474, just know that if you shut down a server with active connections, it can sometimes take up to two minutes before you can successfully restart a server on the same port number. (3b) Remember to shut down your server when done! ------------------------------------------------ Unless you have permission to keep your server up and running, shut it down when you are done: > ./bin/shutdown.sh Use netstat -an to verify that it has been shutdown: > netstat -an @@@ NEXT STEPS... (4) modifying the default configuration for single install (5) modifying the default configuration for shared install