Author: kkolinko
Date: Sun Jun 10 14:11:54 2012
New Revision: 1348600
URL: http://svn.apache.org/viewvc?rev=1348600&view=rev
Log:
CTR: docs
Merged revisions 1348461-1348495 from tomcat/trunk:
r1348461, r1348490 (kkolinko)
Further improvement of RUNNING.txt.
Mention CATALINA_PID, as it is another frequently used environment variable.
Address Mark's review comments.
Document Apache Tomcat Native and Apache Commons Daemon.
........
r1348495 (markt)
Review by native English speaker as requested.
Mostly a/the changes and inserts
Re-worded a few sentences that didn't scan cleanly
Removed the section on Win 95/98/ME since they are all well past end of life.
........
Modified:
tomcat/tc6.0.x/trunk/ (props changed)
tomcat/tc6.0.x/trunk/RUNNING.txt
Propchange: tomcat/tc6.0.x/trunk/
------------------------------------------------------------------------------
Merged /tomcat/trunk:r1348461-1348495
Modified: tomcat/tc6.0.x/trunk/RUNNING.txt
URL:
http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/RUNNING.txt?rev=1348600&r1=1348599&r2=1348600&view=diff
==============================================================================
--- tomcat/tc6.0.x/trunk/RUNNING.txt (original)
+++ tomcat/tc6.0.x/trunk/RUNNING.txt Sun Jun 10 14:11:54 2012
@@ -21,23 +21,24 @@ $Id$
Running The Apache Tomcat 6.0 Servlet/JSP Container
===================================================
-Apache Tomcat 6.0 requires the Java Standard Edition Runtime
+Apache Tomcat @VERSION_MAJOR_MINOR@ requires a Java Standard Edition Runtime
Environment (JRE) version 5.0 or later.
=============================
Running With JRE 5.0 Or Later
=============================
-(1) Download and Install Java SE Runtime Environment (JRE)
+(1) Download and Install a Java SE Runtime Environment (JRE)
-(1.1) Download the Java Standard Edition Runtime Environment (JRE),
+(1.1) Download a Java SE Runtime Environment (JRE),
release version 5.0 or later, from
http://www.oracle.com/technetwork/java/javase/downloads/index.html
(1.2) Install the JRE according to the instructions included with the
release.
- You may also use the full JDK rather than just the JRE.
+ You may also use a full Java Development Kit (JDK) rather than just
+ a JRE.
(2) Download and Install Apache Tomcat
@@ -57,42 +58,44 @@ NOTE: As an alternative to downloading
create your own from the Tomcat source code, as described in
"BUILDING.txt". You can either
- a) Do the full "release" build and find the created distributive in the
+ a) Do the full "release" build and find the created distribution in the
"output/release" directory and then proceed with unpacking as above, or
b) Do a simple build and use the "output/build" directory as
- "CATALINA_HOME". Be warned that there are some differences between
- contents of "output/build" directory and full "release" distributive.
+ "CATALINA_HOME". Be warned that there are some differences between the
+ contents of the "output/build" directory and a full "release"
+ distribution.
(3) Configure Environment Variables
-Tomcat itself is a Java application and does not use environment variables.
-The variables are used by Tomcat startup scripts. The scripts use the
-variables to prepare the command that starts Tomcat.
+Tomcat is a Java application and does not use environment variables. The
+variables are used by the Tomcat startup scripts. The scripts use the variables
+to prepare the command that starts Tomcat.
(3.1) Set CATALINA_HOME (required) and CATALINA_BASE (optional)
-CATALINA_HOME and CATALINA_BASE environment variables are used to
-specify location of Apache Tomcat itself and location of its active
+The CATALINA_HOME and CATALINA_BASE environment variables are used to
+specify the location of Apache Tomcat and the location of its active
configuration, respectively.
-CATALINA_HOME environment variable should be set as defined in (2.2)
-above. Tomcat startup scripts have some logic to set this variable
+The CATALINA_HOME environment variable should be set as defined in (2.2)
+above. The Tomcat startup scripts have some logic to set this variable
automatically if it is absent (based on the location of the script in
-Unixes and on the current directory in Windows), but it might be not
-perfect.
+Unixes and on the current directory in Windows), but this logic might not work
+in all circumstances.
-CATALINA_BASE environment variable is optional and is further described
-in "Multiple Tomcat Instances" section below. If it is absent, it defaults
+The CATALINA_BASE environment variable is optional and is further described
+in the "Multiple Tomcat Instances" section below. If it is absent, it defaults
to be equal to CATALINA_HOME.
+
(3.2) Set JRE_HOME or JAVA_HOME (required)
-JRE_HOME variable is used to specify location of a JRE or JDK that is used
-to start Tomcat.
+The JRE_HOME variable is used to specify location of a JRE that is used to
+start Tomcat.
-JAVA_HOME variable is used to specify location of a JDK. It is used instead
+The JAVA_HOME variable is used to specify location of a JDK. It is used instead
of JRE_HOME.
Using JAVA_HOME provides access to certain additional startup options that
@@ -100,34 +103,55 @@ are not allowed when JRE_HOME is used.
If both JRE_HOME and JAVA_HOME are specified, JRE_HOME is used.
-(3.3) Other variables (optional)
-
-There exist other environment variables, besides the four described above.
-See the comment at the top of catalina.bat or catalina.sh scripts for
-the list and description of them.
-One frequently used variable is CATALINA_OPTS. It allows to specify
-additional options for java command that starts Tomcat.
+(3.3) Other variables (optional)
-See Java documentation for options that affect Java Runtime Environment.
+Other environment variables exist, besides the four described above.
+See the comments at the top of catalina.bat or catalina.sh scripts for
+the list and a description of each of them.
+
+One frequently used variable is CATALINA_OPTS. It allows specification of
+additional options for the java command that starts Tomcat.
+
+See the Java documentation for the options that affect the Java Runtime
+Environment.
+
+See the "System Properties" page in the Tomcat Configuration Reference for
+the system properties that are specific to Tomcat.
+
+A similar variable is JAVA_OPTS. It is used less frequently. It allows
+specification of options that are used both to start and to stop Tomcat as well
+as for other commands.
+
+Do not use JAVA_OPTS to specify memory limits. You do not need much memory
+for a small process that is used to stop Tomcat. Those settings belong to
+CATALINA_OPTS.
+
+Another frequently used variable is CATALINA_PID (on *nix platforms only). It
+specifies the location of the file where process id of the forked Tomcat java
+process will be written. This setting is optional. It will enable the
+following features:
+
+ - better protection against duplicate start attempts and
+ - allows forceful termination of Tomcat process when it does not react to
+ the standard shutdown command.
-See System Properties page in Configuration Reference for system properties
-that are specific to Tomcat.
(3.4) setenv script (optional)
-Except CATALINA_HOME and CATALINA_BASE, all other environment variables can
-be specified in "setenv" script.
+Apart from CATALINA_HOME and CATALINA_BASE, all environment variables can
+be specified in the "setenv" script.
The script is named setenv.bat (Windows) or setenv.sh (*nix). It can be
placed either into CATALINA_BASE/bin or into CATALINA_HOME/bin. The file
has to be readable.
-By default setenv script file is absent. If setenv script is present both
-in CATALINA_BASE and in CATALINA_HOME, the one in CATALINA_BASE is used.
+By default the setenv script file is absent. If the setenv script is
+present both in CATALINA_BASE and in CATALINA_HOME, the one in
+CATALINA_BASE is used.
-For example, to configure JRE_HOME variable you can create the following
-script file:
+For example, to configure the JRE_HOME and CATALINA_PID variables you can
+create the following script file:
On Windows, %CATALINA_BASE%\bin\setenv.bat:
@@ -137,9 +161,10 @@ On Windows, %CATALINA_BASE%\bin\setenv.b
On Unix, $CATALINA_BASE/bin/setenv.sh:
JRE_HOME=/usr/java/latest
+ CATALINA_PID="$CATALINA_BASE/tomcat.pid"
-You cannot configure CATALINA_HOME or CATALINA_BASE variable in setenv
-script, because they are used to find that file.
+You cannot configure CATALINA_HOME and CATALINA_BASE variables in the
+setenv script, because they are used to find that file.
(4) Start Up Tomcat
@@ -190,7 +215,7 @@ binary distribution shared among multipl
this possible, you can set the CATALINA_BASE environment variable to the
directory that contains the files for your 'personal' Tomcat instance.
-When running with separate CATALINA_HOME and CATALINA_BASE, the files
+When running with a separate CATALINA_HOME and CATALINA_BASE, the files
and directories are split as following:
In CATALINA_BASE:
@@ -205,7 +230,7 @@ In CATALINA_BASE:
* conf - Server configuration files (including server.xml)
- * lib - Libraries and classes
+ * lib - Libraries and classes, as explained below
* logs - Log and output files
@@ -228,10 +253,10 @@ In CATALINA_HOME:
* lib - Libraries and classes, as explained below
* endorsed - Libraries that override standard "Endorsed Standards"
- libraries provided by JRE. See Classloading documentation
- in the User Guide for details.
+ libraries provided by JRE. See Classloading documentation
+ in the User Guide for details.
- By default this "endorsed" directory is absent.
+ By default this "endorsed" directory is absent.
In the default configuration the JAR libraries and classes both in
CATALINA_BASE/lib and in CATALINA_HOME/lib will be added to the common
@@ -276,7 +301,7 @@ application deployment.
Troubleshooting
================
-There are only really 3 things likely to go wrong during the stand-alone
+There are only really 2 things likely to go wrong during the stand-alone
Tomcat install:
(1) The most common hiccup is when another web server (or any process for that
@@ -291,19 +316,10 @@ Tomcat install:
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.
-
- 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.
+ port to 1977, you would request the URL http://localhost:1977/ in your
+ browser.
- 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
+(2) 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".
@@ -311,3 +327,128 @@ Tomcat install:
In Firefox, this is under Tools/Preferences -> Advanced/Network ->
Connection -> Settings..., and in Internet Explorer it is Tools ->
Internet Options -> Connections -> LAN Settings.
+
+
+====================
+Optional Components
+====================
+
+The following optional components may be included with the Apache Tomcat binary
+distribution. If they are not included, you can install them separately.
+
+ 1. Apache Tomcat Native library
+
+ 2. Apache Commons Daemon service launcher
+
+Both of them are implemented in C language and as such have to be compiled
+into binary code. The binary code will be specific for a platform and CPU
+architecture and it must match the Java Runtime Environment executables
+that will be used to launch Tomcat.
+
+The Windows-specific binary distributions of Apache Tomcat include binary
+files for these components. On other platforms you would have to look for
+binary versions elsewhere or compile them yourself.
+
+If you are new to Tomcat, do not bother with these components to start with.
+If you do use them, do not forget to read their documentation.
+
+
+Apache Tomcat Native library
+-----------------------------
+
+It is a library that allows to use the "Apr" variant of HTTP and AJP
+protocol connectors in Apache Tomcat. It is built around OpenSSL and Apache
+Portable Runtime (APR) libraries. Those are the same libraries as used by
+Apache HTTPD Server project.
+
+This feature was especially important in the old days when Java performance
+was poor. It is less important nowadays, but it is still used and respected
+by many. See Tomcat documentation for more details.
+
+For further reading:
+
+ - Apache Tomcat documentation
+
+ * Documentation for APR/Native library in the Tomcat User's Guide
+
+ http://tomcat.apache.org/tomcat-@VERSION_MAJOR_MINOR@-doc/apr.html
+
+ * Documentation for the HTTP and AJP protocol connectors in the Tomcat
+ Configuration Reference
+
+
http://tomcat.apache.org/tomcat-@VERSION_MAJOR_MINOR@-doc/config/http.html
+
+ http://tomcat.apache.org/tomcat-@VERSION_MAJOR_MINOR@-doc/config/ajp.html
+
+ - Apache Tomcat Native project home
+
+ http://tomcat.apache.org/native-doc/
+
+ - Other projects
+
+ * OpenSSL
+
+ http://openssl.org/
+
+ * Apache Portable Runtime
+
+ http://apr.apache.org/
+
+ * Apache HTTP Server
+
+ http://httpd.apache.org/
+
+To disable Apache Tomcat Native library:
+
+ - To disable Apache Tomcat Native library when it is installed, or
+ - To remove the warning that is logged during Tomcat startup when the
+ library is not installed:
+
+ Edit the "conf/server.xml" file and remove "AprLifecycleListener" from
+ it.
+
+The binary file of Apache Tomcat Native library is usually named
+
+ - "tcnative-1.dll" on Windows
+ - "libtcnative-1.so" on *nix systems
+
+
+Apache Commons Daemon
+----------------------
+
+Apache Commons Daemon project provides wrappers that can be used to
+install Apache Tomcat as a service on Windows or as a daemon on *nix
+systems.
+
+The Windows-specific implementation of Apache Commons Daemon is called
+"procrun". The *nix-specific one is called "jsvc".
+
+For further reading:
+
+ - Apache Commons Daemon project
+
+ http://commons.apache.org/daemon/
+
+ - Apache Tomcat documentation
+
+ * Installing Apache Tomcat
+
+ http://tomcat.apache.org/tomcat-@VERSION_MAJOR_MINOR@-doc/setup.html
+
+ * Windows service HOW-TO
+
+
http://tomcat.apache.org/tomcat-@VERSION_MAJOR_MINOR@-doc/windows-service-howto.html
+
+The binary files of Apache Commons Daemon in Apache Tomcat distributions
+for Windows are named:
+
+ - "tomcat@VERSION_MAJOR@.exe"
+ - "tomcat@version_ma...@w.exe"
+
+These files are renamed copies of "prunsrv.exe" and "prunmgr.exe" from
+Apache Commons Daemon distribution. The file names have a meaning: they are
+used as the service name to register the service in Windows, as well as the
+key name to store distinct configuration for this installation of
+"procrun". If you would like to install several instances of Tomcat
@VERSION_MAJOR_MINOR@
+in parallel, you have to further rename those files, using the same naming
+scheme.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
