You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by yo...@apache.org on 2004/08/30 19:27:21 UTC
cvs commit: jakarta-tomcat-5 BUILDING.txt RELEASE-NOTES RUNNING.txt
yoavs 2004/08/30 10:27:21
Modified: . BUILDING.txt RELEASE-NOTES RUNNING.txt
Log:
Updated docs for 5.5.0.
Revision Changes Path
1.34 +15 -4 jakarta-tomcat-5/BUILDING.txt
Index: BUILDING.txt
===================================================================
RCS file: /home/cvs/jakarta-tomcat-5/BUILDING.txt,v
retrieving revision 1.33
retrieving revision 1.34
diff -u -r1.33 -r1.34
--- BUILDING.txt 29 Aug 2004 18:14:40 -0000 1.33
+++ BUILDING.txt 30 Aug 2004 17:27:20 -0000 1.34
@@ -1,8 +1,8 @@
$Id$
-
+ =============================================
Building The Tomcat 5.5 Servlet/JSP Container
- ===========================================
+ =============================================
This subproject contains the source code for Tomcat 5.5, a container that
implements the Servlet 2.4 and JSP 2.0 specifications from the Java
@@ -107,4 +107,15 @@
In addition, "ant build-depends" will build packages that
tomcat depends on ( commons-logging for now ), to ease fixes
-and debuging in those packages.
\ No newline at end of file
+and debuging in those packages.
+
+(5) Building The "compat" Package
+
+Tomcat 5.5 is designed to run on J2SE 5.0, but will run on
+J2SE versions 1.3 and 1.4 as well as long as the compatability
+package is placed in the server classpath. See "RUNNING.txt"
+in this directory for running instructions. To build the
+compat package, do
+
+ cd ${tomcat.source}
+ ant build-compat
\ No newline at end of file
1.21 +68 -98 jakarta-tomcat-5/RELEASE-NOTES
Index: RELEASE-NOTES
===================================================================
RCS file: /home/cvs/jakarta-tomcat-5/RELEASE-NOTES,v
retrieving revision 1.20
retrieving revision 1.21
diff -u -r1.20 -r1.21
--- RELEASE-NOTES 30 Aug 2004 16:00:06 -0000 1.20
+++ RELEASE-NOTES 30 Aug 2004 17:27:21 -0000 1.21
@@ -7,13 +7,14 @@
$Id$
-============================
+=============================
KNOWN ISSUES IN THIS RELEASE:
-============================
+=============================
-* Tomcat 5.5 and JNI Based Applications
-* Tomcat 5.5 Standard APIs Available
-* Tomcat 5.5 and XML Parsers
+* Dependency Changes
+* JNI Based Applications
+* Bundled APIs
+* XML Parsers
* Web application reloading and static fields in shared libraries
* JAVAC leaking memory
* Tomcat on Linux
@@ -25,9 +26,24 @@
* When all else fails
--------------------------------------
-Tomcat 5.5 and JNI Based Applications:
--------------------------------------
+===================
+Dependency Changes:
+===================
+Tomcat 5.5 is designed to run on J2SE 5.0 and later, and requires
+configuration to run on J2SE versions 1.3 and 1.4. Make sure to
+read the "RUNNING.txt" file in this directory if you are using
+J2SE version 1.3 or 1.4.
+
+In addition, Tomcat 5.5 depends on the Eclipse JDT for compiling
+JSP pages. This means you no longer need to have the complete
+Java Development Kit (JDK) to run Tomcat, but a Java Runtime Environment
+(JRE) is sufficient. The Eclipse JDT is bundled with the binary
+Tomcat distributions.
+
+
+=======================
+JNI Based Applications:
+=======================
Applications that require native libraries must ensure that the libraries have
been loaded prior to use. Typically, this is done with a call like:
@@ -47,9 +63,9 @@
during the lifetime of a particular JVM.
-----------------------------------
-Tomcat 5.5 Standard APIs Available:
-----------------------------------
+=============
+Bundled APIs:
+=============
A standard installation of Tomcat 5.5 makes all of the following APIs available
for use by web applications (by placing them in "common/lib" or "shared/lib"):
@@ -61,29 +77,28 @@
* commons-pool.jar (Commons Pool 1.1 or later)
* jasper-compiler.jar (Jasper 2 Compiler)
* jasper-runtime.jar (Jasper 2 Runtime)
+* jmx.jar (Java Management Extensions API 1.2 or later)
* jsp-api.jar (JSP 2.0 API)
* commons-el.jar (JSP 2.0 Expression Language)
* naming-common.jar (JNDI Context implementation)
* naming-factory.jar (JNDI object factories for J2EE ENC support)
* naming-resources.jar (JNDI DirContext implementations)
* servlet-api.jar (Servlet 2.4 API)
+* xercesImpl.jar (Xerces XML Parser, version 2.6.2 or later)
You can make additional APIs available to all of your web applications by
putting unpacked classes into a "classes" directory (not created by default),
or by placing them in JAR files in the "lib" directory.
-Tomcat 5.5 also makes Xerces 2 and the Commons Logging API (release 1.0.3 or later)
-available to web applications.
+To override the XML parser implementation or interfaces, see the section below.
-Please note that the JMX API is available to applications as well. The jmx.jar
-file used to be located in the common/lib directory, but was moved to the bin
-directory as part of the Tomcat 5.0.20 release. The jmx.jar is in Tomcat's
-bootstrap classpath (included via the Class Path line in bootstrap.jar's manifest).
+Please note that the JMX API is required by Tomcat while starting up, and thus
+is in Tomcat's bootstrap classpath and placed in the $CATALINA_HOME/bin directory.
---------------------------
-Tomcat 5.5 and XML Parsers:
---------------------------
+============
+XML Parsers:
+============
As described above, Tomcat 5.5 makes an XML parser (and many other standard
APIs) available to web applications. This parser is also used internally
@@ -91,17 +106,15 @@
you may replace the "xercesImpl.jar" file in "common/endorsed" with another
XML parser, as long as it is compatible with the JAXP 1.2 APIs.
-Xerces 2.6.2 is included.
-
On a related note, JDK 1.4 includes Xalan. If you run into Xalan-related
problems, try downloading the latest Xalan version (from
http://xml.apache.org/xalan-j/index.html) and placing the Xalan jar file
in the common/endorsed directory.
----------------------------------------------------------------
+================================================================
Web application reloading and static fields in shared libraries:
----------------------------------------------------------------
+================================================================
Some shared libraries (many are part of the JDK) keep references to objects
instantiated by the web application. To avoid class loading related problems
@@ -114,9 +127,9 @@
"lib" folder, and classes should be put in the "classes" folder).
---------------------
+=====================
JAVAC leaking memory:
---------------------
+=====================
The Java compiler leaks memory each time a class is compiled. Web applications
containing hundreds of JSP files may as a result trigger out of memory errors
@@ -128,9 +141,9 @@
Note: This issue has been fixed in Sun JDK 1.4.x.
----------------
+================
Tomcat on Linux:
----------------
+================
Virtual machine crashes can be experienced when using certain combinations of
kernel / glibc under Linux with Sun Hotspot 1.2 to 1.3. The crashes were
@@ -140,84 +153,39 @@
The problems can be fixed by reducing the default stack size. At bash shell,
do "ulimit -s 2048"; use "limit stacksize 2048" for tcsh.
-GLIBC 2.2 / Linux 2.4 users should also define an environment variable:
+GLIBC 2.2 / Linux 2.4 users may also define an environment variable:
export LD_ASSUME_KERNEL=2.2.5
Additionally, Redhat Linux 9.0 users should use the same setting, to avoid
stability problems.
-----------------------------
+=============================
Enabling SSI and CGI Support:
-----------------------------
+=============================
-Having CGI and SSI available to web applications created security problems when
-using a security manager (as a malicious web application could use them to
-sidestep the security manager access control). In Tomcat 5.5, they have been
-disabled by default, as our goal is to provide a fully secure default
-configuration. However, CGI and SSI remain available.
-
-
-To enable CGI:
-* rename the file $CATALINA_HOME/server/lib/servlets-cgi.renametojar to
- $CATALINA_HOME/server/lib/servlets-cgi.jar.
-* in $CATALINA_HOME/conf/web.xml, you will need to uncomment 2 areas, the
- servlet declaration and the servlet mapping. The servlet declaration
- looks similar to this:
- <servlet>
- <servlet-name>cgi</servlet-name>
- ...
- </servlet>
-
- While the servlet mapping looks similar to this:
- <servlet-mapping>
- <servlet-name>cgi</servlet-name>
- <url-pattern>/cgi-bin/*</url-pattern>
- </servlet-mapping>
-
- Alternately, these servlet declarations and mappings
- can be added to your web application deployment descriptor.
-
-To enable SSI:
-* rename the file $CATALINA_HOME/server/lib/servlets-ssi.renametojar to
- $CATALINA_HOME/server/lib/servlets-ssi.jar.
-* in $CATALINA_HOME/conf/web.xml, you will need to uncomment 2 areas, the
- servlet declaration and the servlet mapping. The servlet declaration
- looks similar to this:
- <servlet>
- <servlet-name>ssi</servlet-name>
- ...
- </servlet>
-
- While the servlet mapping looks similar to this:
- <servlet-mapping>
- <servlet-name>ssi</servlet-name>
- <url-pattern>*.shtml</url-pattern>
- </servlet-mapping>
+Because of the security risks associated with CGI and SSI available
+to web applications, these features are disabled by default.
- Alternately, these servlet declarations and mappings
- can be added to your web application deployment descriptor.
+To enable and configure CGI support, please see the cgi-howto.html page.
+To enable and configue SSI support, please see the ssi-howto.html page.
----------------------
+======================
Security manager URLs:
----------------------
-
-The URLs to be used in the policy file to grant permissions to JARs located
-inside the web application repositories have changed as of Tomcat 4.1.
+======================
-In Tomcat 4.0, codeBase URLs for JARs loaded from web application
-repositories were:
-jar:file:${catalina.home}/webapps/examples/WEB-INF/lib/driver.jar!/-
+In order to grant security permissions to JARs located inside the
+web application repository, use URLs of of the following format
+in your policy file:
-In Tomcat 4.1 and 5.x, they should be:
file:${catalina.home}/webapps/examples/WEB-INF/lib/driver.jar
----------------------------
+============================
Symlinking static resources:
----------------------------
+============================
By default, Unix symlinks will not work when used in a web application to link
resources located outside the web application root directory.
@@ -226,9 +194,9 @@
the check.
-------------------------
+=========================
Enabling invoker servlet:
-------------------------
+=========================
Starting with Tomcat 4.1.12, the invoker servlet is no longer available by
default in all webapps. Enabling it for all webapps is possible by editing
@@ -236,18 +204,20 @@
definition.
Using the invoker servlet in a production environment is not recommended and
-is unsupported.
+is unsupported. More details are available on the Tomcat FAQ at
+http://jakarta.apache.org/tomcat/faq/misc.html#invoker.
+
+
+==============================
+Viewing the Tomcat Change Log:
+==============================
-------------------------
-Viewing the Tomcat Change Log
-------------------------
+See changelog.html in this directory.
-The Change Log for tomcat 5.5 is available at
-http://jakarta.apache.org/tomcat/tomcat-5.5-doc/changelog.html.
--------------------
+====================
When all else fails:
--------------------
+====================
See the FAQ
http://jakarta.apache.org/tomcat/faq/
1.8 +101 -71 jakarta-tomcat-5/RUNNING.txt
Index: RUNNING.txt
===================================================================
RCS file: /home/cvs/jakarta-tomcat-5/RUNNING.txt,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- RUNNING.txt 18 Jun 2004 23:32:53 -0000 1.7
+++ RUNNING.txt 30 Aug 2004 17:27:21 -0000 1.8
@@ -1,91 +1,110 @@
$Id$
+ ============================================
+ Running The Tomcat 5.5 Servlet/JSP Container
+ ============================================
- Running The Tomcat 5 Servlet/JSP Container
- ==========================================
+Out of the box, Tomcat 5.5 requires the Java 2 Standard Edition Runtime
+Environment (JRE) version 5.0 or later. However, you can also run Tomcat
+5.5 on earlier versions of the JRE, as detailed below.
-This subproject contains Tomcat 5, a server that implements the Servlet 2.4
-and JSP 2.0 specifications from the Java Community Process
-<http://www.jcp.org/>. In order to install and run this container, you must do
-the following:
+=============================
+Running With JRE 5.0 Or Later
+=============================
+(1) Download and Install the J2SE Runtime Environment (JRE)
-(0) Download and Install the J2SE Software Development Kit (SDK)
+(1.1) Download the Java 2 Standard Edition Runtime Environment (JRE),
+ release version 5.0 or later, from http://java.sun.com/j2se.
-* Download the Java 2 Standard Edition (J2SE) SDK, release version 1.3 or
- later, from:
+(1.2) Install the JRE according to the instructions included with the
+ release.
- http://java.sun.com/j2se/
+(1.3) Set an environment variable named JAVA_HOME to the pathname of
+ the directory into which you installed the JRE, e.g. c:\j2sdk5.0
+ or /usr/local/java/j2sdk5.0.
-NOTE: Downloading the Java Runtime Environment (JRE) instead is *not*
-sufficient for most users because Tomcat uses the javac.exe that is not
-present in the JRE to compile JSP pages. Unless you are *very* sure of
-what you are doing, please use the full SDK.
-* Install the SDK according to the instructions included with the release.
-
-* Set an environment variable JAVA_HOME to the pathname of the directory
- into which you installed the SDK release.
-
-
-(1) Download and Install the Tomcat 5 Binary Distribution
+(2) Download and Install the Tomcat Binary Distribution
NOTE: As an alternative to downloading a binary distribution, you can create
your own from the Tomcat source repository, as described in "BUILDING.txt".
If you do this, the value to use for "${catalina.home}" will be the "dist"
subdirectory of your source distribution.
-* Download a binary distribution of Tomcat from:
+(2.1) Download a binary distribution of Tomcat from:
- http://jakarta.apache.org/site/binindex.cgi
+ http://jakarta.apache.org/site/binindex.cgi
-* Unpack the binary distribution into a convenient location so that the
- distribution resides in its own directory (conventionally named
- "jakarta-tomcat-5"). For the purposes of the remainder of this document,
- the symbolic name "$CATALINA_HOME" is used to refer to the full
- pathname of the release directory.
+(2.2) Unpack the binary distribution into a convenient location so that the
+ distribution resides in its own directory (conventionally named
+ "jakarta-tomcat-5"). For the purposes of the remainder of this document,
+ the symbolic name "$CATALINA_HOME" is used to refer to the full
+ pathname of the release directory.
-(2) Start Up Tomcat 5
+(3) Start Up Tomcat
-Tomcat 5 can be started by executing the following commands:
+(3.1) Tomcat can be started by executing the following commands:
$CATALINA_HOME\bin\startup.bat (Windows)
$CATALINA_HOME/bin/startup.sh (Unix)
-After startup, the default web applications included with Tomcat 5 will be
-available by visiting:
+(3.2) After startup, the default web applications included with Tomcat will be
+ available by visiting:
- http://localhost:8080/
+ http://localhost:8080/
-Further information about configuring and running Tomcat 5 can be found in
-the documentation included here, as well as on the Tomcat web site:
+(3.3) Further information about configuring and running Tomcat can be found in
+ the documentation included here, as well as on the Tomcat web site:
- http://jakarta.apache.org/tomcat/
+ http://jakarta.apache.org/tomcat/
-(3) Shut Down Tomcat 5
+(4) Shut Down Tomcat
-Tomcat 5 can be shut down by executing the following command:
+(4.1) Tomcat can be shut down by executing the following command:
$CATALINA_HOME\bin\shutdown (Windows)
$CATALINA_HOME/bin/shutdown.sh (Unix)
-(4) Advanced Configuration - Multiple Tomcat 5 Instances
-In many circumstances, it is desirable to have a single copy of a Tomcat 5
+===========================================
+Running Tomcat With J2SE Version 1.4 or 1.3
+===========================================
+
+(1) Obtain the compat package:
+
+(1.1) Download the compat package from the binary download site:
+ http://jakarta.apache.org/site/binindex.cgi
+
+ * Or build this package yourself from the source code: see
+ "BUILDING.txt" in this directory.
+
+(2) Place the compat package jar in Tomcat's server classpath
+ by copying it into the $CATALINA_HOME/server/lib directory.
+
+(3) Follow the same directions for starting and stopping the
+ server as if you were using J2SE 5.0.
+
+
+====================================================
+Advanced Configuration - Multiple Tomcat Instances
+====================================================
+
+In many circumstances, it is desirable to have a single copy of a Tomcat
binary distribution shared among multiple users on the same server. To make
this possible, you can pass a "-Dcatalina.base=$CATALINA_BASE" argument when
executing the startup command (see (2)). In this
"-Dcatalina.base=$CATALINA_BASE" argument, replace $CATALINA_BASE with the
-directory that contains the files for your 'personal' Tomcat 5 instance.
+directory that contains the files for your 'personal' Tomcat instance.
-When you use this "-Dcatalina.base=$CATALINA_BASE" argument, Tomcat 5 will
+When you use this "-Dcatalina.base=$CATALINA_BASE" argument, Tomcat will
calculate all relative references for files in the following directories based
-on the value of $CATALINA_BASE instead of $CATALINA_HOME :
+on the value of $CATALINA_BASE instead of $CATALINA_HOME:
* conf - Server configuration files (including server.xml)
@@ -100,51 +119,62 @@
* temp - Directory used by the JVM for temporary files (java.io.tmpdir)
-If you do not pass the "-Dcatalina.base=$CATALINA_BASE" argument to the startup command, $CATALINA_BASE will default to the same value as $CATALINA_HOME (which means that the same directory is used for all relative path resolutions).
+If you do not pass the "-Dcatalina.base=$CATALINA_BASE" argument to the
+startup command, $CATALINA_BASE will default to the same value as $CATALINA_HOME,
+ which means that the same directory is used for all relative path resolutions.
The administration and manager web applications, which are defined in the
-$CATALINA_BASE/conf/Catalina/localhost/admin.xml and $CATALINA_BASE/conf/Catalina/localhost/manager.xml files, will
+$CATALINA_BASE/conf/Catalina/localhost/admin.xml
+and
+$CATALINA_BASE/conf/Catalina/localhost/manager.xml files, will
not run in that configuration, unless either:
- The path specified in the docBase attribute of the Context element is made
absolute, and replaced respectively by $CATALINA_HOME/server/webapps/admin
and $CATALINA_HOME/server/webapps/manager
-- Both web applications are copied or moved to $CATALINA_BASE, and the path specified in the docBase attribute of the Context element is modified appropriately.
-- Both web applications are disabled by removing $CATALINA_BASE/conf/Catalina/localhost/admin.xml
- and $CATALINA_BASE/conf/Catalina/localhost/manager.xml
+- Both web applications are copied or moved to $CATALINA_BASE,
+ and the path specified in the docBase attribute of the Context
+ element is modified appropriately.
+- Both web applications are disabled by removing
+ $CATALINA_BASE/conf/Catalina/localhost/admin.xml
+ and
+ $CATALINA_BASE/conf/Catalina/localhost/manager.xml.
-(5) Troubleshooting:
+================
+Troubleshooting
+================
There are only really 3 things likely to go wrong during the stand-alone
-Tomcat 5 install:
+Tomcat install:
-1) The most common hiccup is when another web server (or any process for that
- matter) has laid claim to port 8080. This is the default HTTP port that
- Tomcat attempts to bind to at startup. To change this, open the file:
+(1) The most common hiccup is when another web server (or any process for that
+ matter) has laid claim to port 8080. This is the default HTTP port that
+ Tomcat attempts to bind to at startup. To change this, open the file:
$CATALINA_HOME/conf/server.xml
- and search for '8080'. Change it to a port that isn't in use, and is
- greater than 1024, as ports less than or equal to 1024 require superuser
- access to bind under UNIX.
+ and search for '8080'. Change it to a port that isn't in use, and is
+ greater than 1024, as ports less than or equal to 1024 require superuser
+ access to bind under UNIX.
Restart Tomcat and you're in business. Be sure that you replace the "8080"
in the URL you're using to access Tomcat. For example, if you change the
port to 1977, you would request the URL http://localhost:1977/ in your browser.
-2) An "out of environment space" error when running the batch files in
- Windows 95, 98, or ME operating systems.
+(2) An "out of environment space" error when running the batch files in
+ Windows 95, 98, or ME operating systems.
- Right-click on the STARTUP.BAT and SHUTDOWN.BAT files. Click on
- "Properties", then on the "Memory" tab. For the "Initial environment" field,
- enter in something like 4096.
-
- After you click apply, Windows will create shortcuts which you can use to start and stop the container.
-
-3) The 'localhost' machine isn't found. This could happen if you're behind a
- proxy. If that's the case, make sure the proxy configuration for your
- browser knows that you shouldn't be going through the proxy to access the
- "localhost".
+ Right-click on the STARTUP.BAT and SHUTDOWN.BAT files. Click on
+ "Properties", then on the "Memory" tab. For the "Initial environment" field,
+ enter in something like 4096.
+
+ After you click apply, Windows will create shortcuts which you can use
+ to start and stop the container.
+
+(3) The 'localhost' machine isn't found. This could happen if you're behind a
+ proxy. If that's the case, make sure the proxy configuration for your
+ browser knows that you shouldn't be going through the proxy to access the
+ "localhost".
- In Netscape, this is under Edit/Preferences -> Advanced/Proxies, and in
- Internet Explorer, Tools -> Internet Options -> Connections -> LAN Settings.
+ In Netscape, this is under Edit/Preferences -> Advanced/Proxies, and in
+ Internet Explorer, Tools -> Internet Options -> Connections -> LAN Settings.
---------------------------------------------------------------------
To unsubscribe, e-mail: tomcat-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: tomcat-dev-help@jakarta.apache.org