| ||||||||||||||||||||||||||||||||||||
| Important | Please make sure that you read the section on installing Ant, a make-like tool written in Java that we will need later in the book for automating administration tasks. |
The Linux installation notes will be self-contained. If you are planning to deploy Tomcat on Linux, you should skip the next section.
Tomcat Windows Installer
Within the bin folder (on the page http://jakarta.apache.org/builds/jakarta-tomcat-4.0/release/v4.0.4/), you will find at least six distributions. The one we want is called jakarta-tomcat-4.0.4.exe. Save this file at a convenient location on your machine, and double-click the file to begin installation - you must agree with the general Apache License to continue.
The next window allows you to choose to install the following options:
NT Service
Selecting the NT Service option allows you to start, stop, and restart Tomcat in the same way as any other NT service and this option is recommended if you are used to managing your system services in this way.
It is only available for Windows NT, 2000, and XP as Windows 98 is not a server OS. Tomcat will start as soon as the computer is switched on (and so will survive reboots of the machine) and will run in the background even when there is no user logged in. This is clearly the better deployment option, but probably not what you want for development.
| Important | A bug in JDK 1.3 causes the termination of Java services when the user logs off - this has been fixed in JDK 1.4 and so you may wish to choose this as your JDK as mentioned above. |
This option is not available to Windows 98 users, and they will be required to manually start and stop the server. We will discuss how a daemon-like service can be set up for Windows 98 later in this section.
JSP Development Shell Extensions
In brief, this is a very useful scripting tool and it is recommended that you install the extensions.
Start Menu Group
This option adds shortcuts to the Start menu for starting, stopping, and uninstalling the server, as well as shortcuts to the key configuration files, the installation directory, and the documentation.
Tomcat Documentation
The Tomcat documentation is getting better with time and is certainly worth installing.
Example Web Applications
The example web applications may be useful as a reference, however if they are installed and operational, they represent a certain security risk since they provide a documented and known path into your server that may be used for DoS attack attempts. Choose to install them for now as we will use them to check the installation is working correctly, and we will deal with the possible security implications later in Chapter 16.
| Important | The latest information, including security issues with Tomcat, is available at http://jakarta.apache.org/tomcat/news.html. |
Source Code
Finally, if you are keen to have the latest sourcecode or want to ensure that Tomcat will compile from source, it is available. As the majority of this process is identical for all platforms and Ant is required, we will cover it at the end of this chapter, after the installation of Ant.
Setting Environment Variables
In most cases, the various scripts provided with Tomcat will be able to guess the setup of your machine in such a way that no further intervention is strictly necessary. However, it is wise to add the following environment variables.
%CATALINA_HOME%
%CATALINA_HOME% is the directory where Tomcat is installed. Tomcat needs to know this information to find the resources that are referenced as relative paths to this folder. If you chose the default directory while installing, this will be C:\Program Files\Apache Tomcat 4.0.
Catalina, as mentioned in , is the codename of the Tomcat 4 project.
To add the environment variable, navigate to Start | Settings | Control Panel and choose System. Now choose the Advanced tab and select the Environment Variables... button. Now select the New button in the system variables (lower half) section and enter the following values, substituting the path to your installation if it is different to the one shown:
Windows 9x-and ME-Speciflc Issues
In Windows 9x, setting the environment variables is done by editing the file c:\autoexec.bat. Open the file and add the following line:
set CATALINA_HOME=c:\jakarta-tomcat-4.0.4
Notice that because of file length and spaces in the path issues, it is safer to install Tomcat directly onto c:\ rather than under Program Files. You will also need to increase the default environment space to Tomcat by opening a DOS prompt window, right-clicking on it, choosing Properties, selecting the Memory tab, and setting the initial environment to 4096 bytes (4Kb):
It is also possible to set another variable, called %CATALINA_BASE%, that allows multiple instances of the same distribution to be configured independently of each other. This is particularly relevant to hosting providers or other situations where multiple users have access to the same server. This will be discussed in detail in Chapter 19.
Testing the Installation
To test the installation, you must first start the server. We can start the server in two ways - manually or as a service.
Starting the Server Manually
You can do this by going to Start | Programsl Apache Tomcat 4.0 and select the Start Tomcat option - which is probably the easiest for our purposes. The new command prompt window will come up to prove that the server is running.
Alternatively, you can start Tomcat by opening a command prompt window, navigating to %CATALINA_HOME%\bin, and typing startup:
Note that if the window appears and promptly disappears again, you should check that you have not installed the Light Edition, which has no XML parser and will not work without one. Some further trouble-shooting tips are provided at the end of the chapter in case the server will not start up. You may also get error messages if your %JAVA_HOME% variable is not defined, and if the %JAVA_HOME%\bin directory within the JDK is not on the Path. If this is the case, you will get an error message saying:
'java' is not recognized as an internal or external command,
operable program or batch file.
You should refer to the instructions earlier in the book if this is the case.
To shut down Tomcat, use the Shutdown shortcut, Start | Programsl Apache Tomcat 4.0 | Stop Tomcat, or type shutdown into the command prompt from Tomcat's bin directory.
Starting the Server As a Service
If you wish to start the server as a service, and assuming you chose this option when installing the server, you will need to start the service up. In a Windows 2000 installation this is done by choosing the Start | Settings | Control Panel and selecting Administrative Tools from which you can select Services. In the window that opens, there should be an entry for Tomcat as shown opposite:
To start the server, right-click on the Tomcat entry and choose Start. No window will be shown as the server is running as a service, also known as a daemon or background thread. Once the server is started, the options for restarting and stopping the server will also be enabled.
Changing NT Service Options
Looking at the last screenshot once more, you can see the Startup Type is set to Automatic, which means that if we were to restart the computer this would also start an instance of Tomcat automatically. From now on, every time Windows is started, Tomcat will automatically start up at boot time and will be available from then on.
We can further customize the service by choosing the Properties option from the context menu. This allows us to change the startup type to manual or entirely disable the service, plus it allows you to choose to automatically restart the service should it crash. This last option is especially useful as it also allows you to run a script should the server fail, as well as rebooting the computer (although consider seriously what you put in this script as it can offer a security hole if the script does something that might be used as a DoS attack).
It also allows you to carry out different actions depending on how many times it has failed (by choosing the Recovery tab), so you can initially request a reboot of the service, then a reboot of the machine, and then any subsequent failures will cause a script to run that perhaps alerts you of the failure.
Remember that when a Java process fails (that is, the JVM exits with an error) it brings the machine down with it, but the server will continue to run as normal. The only possible reason for restarting the machine is if the applications that are running on Tomcat depend on an ordered bootup and no loss of connections between the applications and their various resources. That means that, on the whole, writing a script that flashes a warning or similar is more desirable than rebooting the system.
If you wish to set the recovery options, right-click on the Tomcat service entry in the list and choose Properties. In the window that opens, choose Recovery and you should be presented with the following options:
As you can see, the default is for no action to be taken. We are going to change this behavior and restart the server a maximum of twice and then run a script on the third and subsequent failures. Select the First failure drop-down box and choose Restart the Service. Do the same for the second box. We will have 1 minute as the time after the crash that the service should be restarted - this should give any external resources enough time to notice the failure and respond if necessary.
If this is a stable server that rarely fails, set the reset level high, say, to 20 days, which should mean that consistent failures are noticed and dealt with. It may be that it fails only occasionally - you want to know nevertheless. Setting the reset level high maximizes the chance that the third option will be run, thus alerting you to the problem. Remember that the script can easily be responsible for restarting the server so that users feel a minimal downtime, yet you are still notified. In fact, this option may be preferable to having the system automatically restart the server without explicit notification of problems.
If the server fails often, it may be necessary to turn the reset level down so that failures can be noticed.
Now choose Run a File from the Subsequent failures option menu. This will enable the Run file menu where you can choose the file to run (normally a batch file). The fail count is passed to the file as a command-line parameter for the script to report.
For the moment, assuming that you have not specified any other command-line prompts, you can discover the failure count using a file like the following:
@echo off
if NOT %1==/fail goto end
echo Number of failures to date is %2 >> T4.fail
:end
cd "c:\Program Files\Apache Tomcat 4.0\bin\"
start startup
The above file is the simplest possible reporting script that merely appends the failure count to a file named T4.fail each time a failure occurs before restarting the server (but not as a service, rather as a manual start in a new command prompt window). Before we move on, let us quickly explain the file. In the first line we turn off echo, the second line checks that the first command-line argument (%1) is equal to /fail and if so prints out the line:
Number of failures to date is %x%
where x is the number of failures. Notice the >> T4.fail codicil makes sure that echo is output to the file T4.fail and that the output is appended to, rather than replaces, the existing contents of the file. A single > would replace the file contents.
The result of multiple failures with this file, as set up above to run on the third failure, would be something along the lines of:
Number of failures to date is %3%
Number of failures to date is %4%
Number of failures to date is %5%
Number of failures to date is %6%
Alternatively, you can run a Java class that extracts the information and perhaps e-mails the failure to you. To do this, simply forward the fail count to your program, calling it as follows:
@echo off
if NOT %1==/fail goto end
java ReportTomcatFailure %2
:end
cd "c:\Program Files\Apache Tomcat 4.0\bin\"
start startup
The number of failures is now available as ReportTomcatFailure's first command-line argument (accessible as args [ 0 ]).
In addition to the security risk involved in having the computer automatically reboot itself, it is not entirely necessary. Since Tomcat runs within a JVM, unless you are doing something unusual, a failure of the Tomcat instance is isolated from the rest of the system and a "soft" reboot should suffice for most problems. This puts hardware reboots in the very serious category, and as such, they are something that you probably want to control manually.
Tomcat 4 As a Daemon Thread
If you chose not to run Tomcat as an NT service, or were unable to because you are running Windows 9x/ME, you can still run Tomcat without a command prompt/DOS prompt window being open all the time that Tomcat is running.
To do this, you will need to amend the catalina.bat file in %CATALINA_HOME%\bin. Search and replace the text:
%_RUNJAVA%
with:
%_RUNJAVAW%
Note the added W character. This new command calls the window-less version of the java executable using startup.bat, which is again in the %CATALINA_HOME%\bin directory. Tomcat will now start with no attached Tomcat window, although one will appear and disappear.
| Important | You should create a shortcut to startup.bat as the provided shortcuts in the Start menu will not start a daemon process. |
Since the appearing-disappearing window resembles a port contention problem, you should now check that the server is running by attempting to connect to it with a telnet session or using a browser. If it is not running, run the startup.bat file from the %CATALINA_HOME%\bin folder and look at the error message, which should explain the problem.
Viewing the Default Installation
Tomcat, like most servers, comes with a default home page that can be used to check the installation is working. Enter the following address in a browser: http://localhost:8080/.
The following page should come up:
Port Numbers
Note that if you are not used to the port number assignation (the : 8080 section of the address), including it in the address of the server is required in the default installation. Ports are logical addresses in a computer that allow multiple communications with the server and the channeling of different protocols. For example, POP3 traffic is commonly addressed to port 25, while SMTP is addressed to port 110, SSL is addressed to port 21, telnet to 23, and so on. Browsers automatically point at port 80 if no port is specified (443 for HTTPS); hence the use of ports is not immediately visible to the average user.
| Important | As the majority of server hardware already includes a standard web server installation, usually Apache for Linux and IIS for Windows, Tomcat does not attempt to connect to the standard HTTP traffic port, which is 80 by default, but rather to port 8080. |
The configuration file that specifies the port number is called server.xml and can be found in the installation folder of Tomcat in the %CATLINA_HOME%\conf directory. It's just a text file and somewhere within it you should find the following entry:
<!-- Define a non-SSL HTTP/1.1 Connector on port 8080 -->
<Connector className="org.apache.catalina.connector.http.HttpConnector"
port="8080" minProcessors="5" maxProcessors="75"
enableLookups="true" redirectPort="8443"
acceptCount="10" debug="0" connectionTimeout="60000"/>
You can find this entry by searching for the string 'port ="8080"'. Changing this to another number will change the Tomcat port number. Changing it to 80 will allow you to connect to Tomcat using the following URL http://localhost/ without the trailing colon and port number.
If you have any problems, refer to the Troubleshooting and Tips section at the end of this chapter.
On the other hand, if all has gone well, you are now the proud owner of your own Tomcat instance. Before we finish, we should check Tomcat's ability to serve JSP pages and servlets - there is nothing in the default welcome page that is dynamically generated, so we have not yet tested the JSP and servlet functionality.
To do this, choose the JSP Examples link from the left-hand menu and select some of the examples to run. Check that they all run as they are supposed to without error messages. Do the same for the Servlet Examples link to test this functionality. Let's now take a look at installing Tomcat on Windows using a ZIP file.
Installing Tomcat On Windows Using the ZIP File
Installing Tomcat using the ZIP file is not much different from the process described above. The ZIP file is provided for those concerned with the security implications of downloading and running an executable over the Internet. The ZIP file is significantly bigger than the executable installer but has the same contents.
To install Tomcat using the ZIP, simply unpack the contents of the file, traditionally to C:\Program Files\Jakarta Tomcat 4.0.
Now add the %CATALINA_HOME% environment variable as above. To check your installation, you will need to follow slightly different instructions than before. As the shortcuts for the server will not be create automatically, you will need to call a couple of batch files provided in the %CATALINA_HOME%\bin directory for this purpose.
To start the server, either navigate to %CATALINA_HOME%\bin within the command prompt and type:
> cd %CATALINA_HOME%\bin
> startup.bat
Alternatively, you can start the server from the command prompt from any directory by adding the path C:\Program Files\Jakarta Tomcat 4.0 to the Path variable before calling the startup file as follows:
> set path=%path%;c:\Program Files\Jakarta Tomcat 4.0
> startup
A new window will open as with the previous installation method showing that the server has started. To shut down Tomcat type shutdown.
Installing Tomcat from Source
Installing Tomcat from the sourcecode is usually done to benefit from the latest developments after bug fixes or feature releases and sometimes a developer may do this to incorporate bug repairs in the source. In Linux it is far more common for servers to be built for the system, however it is still not strictly necessary with a server such as Tomcat that is written in Java.
Tomcat is conventionally built using the Jakarta Ant utility. Ant is used for automated project building, including compilation and deployment, and benefits from the system independence that Java enjoys as it is written in Java. It uses a variety of configuration files provided with Tomcat to build Tomcat and to deploy it.
In addition to being used to build Tomcat, Ant can also be used to carry out a number of administrative actions on Tomcat with the help of additional files and this is discussed in Chapter 17.
As the procedure for installing Tomcat from source is the same for Linux and Windows, we shall cover it in full after looking at the Linux binary distributions and Ant installation.
Installing Tomcat On Linux
Installing Tomcat on Linux or Unix is easy. Many of the problems that existed with the other branch of Tomcat development, the 3.2.x line, do not exist for Tomcat 4. Download either the ZIP file or gzipped tar file if you have GNU gzip. The files can be found at http://jakarta.apache.org/builds/jakarta-tomcat-4.0/release/v4.0.4/bin/. If you have any problem finding it, try navigating to it from the Tomcat project site http://jakarta.apache.org/tomcat/.
The Light Edition, available as jakarta-tomcat-4.0.4-LE-jdk14.zip and jakarta-tomcat-4.0.4-LE-jdk14.tar.gz does not contain Xerces, an XML parser required by Tomcat, and is therefore 1.2Mb lighter in download size. This edition is aimed at installations on top of the 1.4 JDK, which has an XML parser included. In addition, the Light Edition does not provide support for JNDI or JavaMail, the JDBC 2 Extensions, or Tyrex (security, transactions, and resource pooling).
If you are using JDK 1.3, then download either jakarta-tomcat-4.0.4.tar.gz or jakarta-tomcat-4.0.4.zip. Also if you have any stability issues with Tomcat 4 on JDK 1.4 then it may be worth installing the complete binary before going to the trouble of installing 1.3 JDK; since the 1.4 JDK itself is very stable it is likely that it is Tomcat that is the problem.
RPMs are available for installation in the rpms folder if you prefer. Alternatively, the ZIP file has exactly the same contents, and you can then simply unzip the file without compatibility issues.
| Important | Opera 6.0 occasionally crashes, presumably because it does not recognize the tar MIME type. If you have these problems, try another browser or use the ZIP file. |
Unzip (and untar if necessary) the file onto your hard drive to a path such as /usr/Java/jakarta-tomcat-4.0.4.
Installing the RPM for the full version 4.0.4 was done as follows:
# rpm -iv tomcat4-4.0.4-full.2jpp.noarch.rpm
noarch signifies the package is suitable for all architectures.
You should now export the $CATALINA_HOME variable, using the following command (in bash):
# CATALINA_HOME=/usr/java/jakarta-tomcat-4.04
# export CATALINA_HOME
Alternatively, add these commands to ~/ .bashrc or /etc/profile as we did for the JDK installation or create a shell file, tomcat.sh, and place it in /etc/profile.d. It will be run automatically by /etc/profile at boot time to make the variable available to all users.
Catalina, as mentioned in , is the codename of the Tomcat 4 project.
You can now start Tomcat by running the following shell command:
# $CATALINA_HOME/bin/startup.sh
You can shut down Tomcat using shutdown.sh. If you want a script for restarting the server, copy and rename shutdown.sh as restart.sh and add the following line to the end:
exec "$PRGDIR"/"$EXECUTABLE" start "$@"
or simply write a script that calls shutdown followed by startup.
Viewing the Default Installation
To check that Tomcat is running, point your browser to http://localhost:8080/. You should see the following screenshot:
Choose the JSP Examples link from the left-hand side menu and select some of the examples to run. Check that they run without error messages. Do the same for the Servlet Examples to test this functionality.
Port Numbers
Tomcat uses port 8080 by default, as in Linux and Unix systems root permission is required to assign port numbers below 1024 to a process. Thus, to make things simple, the port number chosen should be one that is greater than 1024. As the majority of server hardware already includes a standard web server installation, usually Apache, Tomcat does not attempt to connect to the standard HTTP traffic port, 80, by default.
If you wish to use Tomcat as a standalone server without providing the port number in the address bar (by using 80), you will firstly need root privileges.
The configuration file that specifies the port number is called server.xml and can be found in the $CATALINA_HOME/conf directory. Somewhere within it you should find the following entry:
<!-- Define a non-SSL HTTP/1.1 Connector on port 8080 -->
<Connector className="org.apache.catalina.connector.http.HttpConnector"
port="8080" minProcessors="5" maxProcessors="75"
enableLookups="true" redirectPort="8443"
acceptCount="10" debug="0" connectionTimeout="60000"/>
You can find this entry by grepping for the string 'port="8080"'. Changing this to another number (over 1024 in Linux) will change the Tomcat port number. Changing it to 80 will allow you to connect to Tomcat using the following URL: http://localhost/, providing that the server is started with root permissions.
If you have any problems, refer to the Troubleshooting and Tips section at the end of this chapter.
Running Tomcat with the Server Option
Earlier we discussed running the Java executable with the server option, which will increase its efficiency and thus perform better. To run Tomcat with the server option, we will need to modify a number of files in its bin directory. For Windows, we need to edit setclasspath.bat. The last three lines should be changed as follows:
set _RUNJAVA="%JAVA_HOME%\bin\java" -server
set _RUNJAVAW="%JAVA_HOME%\bin\javaw" -server
set _RUNJDB="%JAVA_HOME%\bin\jdb" -server
Of course this assumes that you are manually starting Tomcat (or that you have copied the shortcut into the Startup folder on Windows 98).
Linux is very similar. This time we modify setclasspath.sh:
_RUNJAVA="$JAVA_HOME"/bin/java -server
_RUNJDB="$JAVA_HOME"/bin/jdb -server
Alternatively, a simpler option that will work on every platform is to amend the file $JAVA_HOME/jre/lib/jvm.cfg. Usually, the file will look something like this:
#
# @(#)jvm.cfg 1.2 99/07/09
#
# Copyright 1999 by Sun Microsystems, Inc.,
# 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
# All rights reserved.
#
# List of JVMs that can be used as the first option to java, javac, etc.
# Order is important -- first in this list is the default JVM.
#
-hotspot
-server
-classic
As you can see the client JVM is the default. To make server the default, change the order of these so that -server comes first in the list.
If the file is somewhat different, with extra settings for native versus green threads, don't worry; the principle is essentially the same. If the file is not present, then the option above is the only one available - Sun have removed it from JDK 1.4.
No comments:
Post a Comment