danmil 01/02/01 08:52:26 Modified: src/doc Tag: tomcat_32 tomcat-ssl-howto.html tomcat-apache-howto.html src/doc/uguide Tag: tomcat_32 tomcat_ug.html Log: Cleaned up HTML, fixed typos. Contributed by Chris Pepper Revision Changes Path No revision No revision 1.1.2.3 +194 -141 jakarta-tomcat/src/doc/tomcat-ssl-howto.html Index: tomcat-ssl-howto.html =================================================================== RCS file: /home/cvs/jakarta-tomcat/src/doc/tomcat-ssl-howto.html,v retrieving revision 1.1.2.2 retrieving revision 1.1.2.3 diff -u -r1.1.2.2 -r1.1.2.3 --- tomcat-ssl-howto.html 2000/12/11 17:13:30 1.1.2.2 +++ tomcat-ssl-howto.html 2001/02/01 16:52:21 1.1.2.3 @@ -1,3 +1,4 @@ + @@ -45,41 +46,61 @@ +

Tomcat and SSL

-

By Gomez Henri <hgomez@slib.fr>

+ +

By Gomez Henri <hgomez@slib.fr>

+

Table of Contents

+ +
+

Tomcat and SSL

-

Tomcat could use SSL directly (via an HTTP connector supporting SSL) or via - an Apache SSLified (Apache-SSL or apache-mod_ssl) + +

Tomcat can use SSL directly (via an HTTP connector supporting SSL) or via + an SSL-capable Apache (Apache-SSL or apache+mod_ssl) with the mod_jk connector.

+
+

Building tomcat with SSL support

-

If you want to rebuild the tomcat with SSL, be carefull of your CLASSPATH. - I used to clear the CLASSPATH env var to avoid conflict in jar. A common case - of conflict is for XML parsers (xerces & jaxp). tomcat need a recent XML parser - like Apache Group xerces 1.1.2 or Sun's jaxp 1.0.1.

-

At build time, (via ant), tomcat will check for some libs and will then included - more or less options. It's the case of SSL support. If you have the JSSE 1.0.2 - jars in your CLASSPATH, tomcat will be built with SSL (SSLSocketFactory). tomcat - will use the JSSE jars (jcert.jar, jsse.jar, jnet.jar).This software COULDN'T - BE INCLUDED in tomcat. You'll have to go to jsse - home page and download from there the domestic (US/Canada) or global archive. - Then copy the 3 jars in tomcat runtime classpath lib ($TOMCAT_HOME/lib).

+ +

If you want to rebuild tomcat with SSL, be careful of your + CLASSPATH. I used to clear the CLASSPATH environment variable to avoid + conflict in jar. A common cause of conflict is XML parsers (xerces + & jaxp). Tomcat needs a recent XML parser like the Apache Group's + xerces 1.1.2 or Sun's jaxp 1.0.1.

+

At build time, (via ant), tomcat will check for some libs and will + then include various options, possibly including SSL support. If you + have the JSSE 1.0.2 jars in your CLASSPATH, tomcat will be built with + SSL (SSLSocketFactory). Tomcat will use the JSSE jars (jcert.jar, + jsse.jar, jnet.jar). This software COULDN'T BE INCLUDED in tomcat. + You'll have to go to the jsse home page and + download the domestic (US/Canada) or global archive from there. Then + copy the 3 jars into tomcat's runtime classpath lib + ($TOMCAT_HOME/lib).

+
+

Tomcat with Apache and mod_jk

-

If you use Apache with SSL (apache-ssl or apache-mod_ssl), the apache connector - mod_jk will be able to forward to tomcat some SSL informations if JkExtractSSL - directive is present in your httpd.conf.

-

Informations are :

+ +

If you use Apache with SSL (Apache-SSL or apache+mod_ssl) and the + JkExtractSSL directive in httpd.conf, the apache connector + mod_jk will be able to pass some SSL information to tomcat.

+

This information is:

+ @@ -98,8 +119,10 @@
HTTPSSSL Certificate of client
-

Since apache-ssl and apache-mod_ssl use differents env vars, you could adapt - SSL vars via the following JK vars

+ +

Since Apache-SSL and apache+mod_ssl use different environment variables, you + can set SSL variables from the following JK variables

+ -

here is an example of directive to include in httpd.conf for use with mod_ssl -

-

# Should mod_jk send SSL - information to Tomact (default is On)
- JkExtractSSL On
- # What is the indicator for SSL (default is HTTPS)
- JkHTTPSIndicator HTTPS
- # What is the indicator for SSL session (default is SSL_SESSION_ID)
- JkSESSIONIndicator SSL_SESSION_ID
- # What is the indicator for client SSL cipher suit (default is SSL_CIPHER)
- JkCIPHERIndicator SSL_CIPHER
- # What is the indicator for the client SSL certificated (default is SSL_CLIENT_CERT) -
- JkCERTSIndicator SSL_CLIENT_CERT

-

When using mod_jk with Apache & mod_ssl it is essential to specify "SSLOptions - +StdEnvVars +ExportCertData" in the httpd.conf file.
- Otherwise mod_ssl will not produce the neccessary environment variables for + +

here is an example of directives to include in httpd.conf for use with + mod_ssl:

+ +
# Should mod_jk send SSL information to Tomcat (default is On)
  +JkExtractSSL On
  +# What is the indicator for SSL (default is HTTPS)
  +JkHTTPSIndicator HTTPS
  +# What is the indicator for SSL session (default is SSL_SESSION_ID)
  +JkSESSIONIndicator SSL_SESSION_ID
  +# What is the indicator for client SSL cipher suit (default is SSL_CIPHER)
  +JkCIPHERIndicator SSL_CIPHER
  +# What is the indicator for the client SSL certificated (default is SSL_CLIENT_CERT)
  +JkCERTSIndicator SSL_CLIENT_CERT
  +
+ +

When using mod_jk with Apache & mod_ssl it is essential to specify + "SSLOptions +StdEnvVars +ExportCertData" in the httpd.conf file.
+ Otherwise mod_ssl will not produce the necessary environment variables for mod_jk. (Tilo Christ <tilo.christ@med.siemens.de>)

-

Warning, even if mod_jk support both ajp12 (old version from ApacheJServ) and - ajp13, only ajp13 could forward SSL informations to tomcat.

+

Warning: Even if mod_jk supports both ajp12 (the old version from + Apache JServ) and ajp13, only ajp13 can forward SSL information to + tomcat.

+
-

SSL via apache

-

mod_jk seems to support the VirtualHost directive of Apache. It's specialy - usefull when using an apache-mod_ssl with tomcat.
+ +

SSL via Apache

+ +

mod_jk seems to support the VirtualHost directive of Apache. It's especially + useful when using apache+mod_ssl with tomcat.
This config will easily secure your webapps via Apache SSL support. Just take - care of setting these jk vars outside VirtualHost directives :

-

JkWorkersFile /etc/httpd/conf/workers.properties
- JkLogFile /var/log/httpd/mod_jk.log
- JkLogLevel warn

-

The jk redirect stuff could be set in virtual hosts :

-

<VirtualHost _default_:443>
- SSLEngine on
- SSLCipherSuite ALL:!ADH:!EXP56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL -
-
-
# other SSL stuff
-

- Alias /alesia "/var/tomcat/webapps/alesia" -
- <Directory "/var/tomcat/webapps/alesia">

- Options Indexes FollowSymLinks -
- </Directory>
-
- JkMount /alesia/servlet/* ajp13
- JkMount /alesia/*.jsp ajp13
-

- <Location "/alesia/WEB-INF/">
- AllowOverride None
- Deny from all
- </Location>

-

</VirtualHost>

+ care of setting these JK variables outside VirtualHost directives:

+ +
JkWorkersFile /etc/httpd/conf/workers.properties
  +JkLogFile /var/log/httpd/mod_jk.log
  +JkLogLevel warn
  +
+ +

The JK redirect stuff could be set in virtual hosts: <virtualhost + _default_:443>

+ +
<VirtualHost _default_:443>
  +SSLEngine on
  +SSLCipherSuite ALL:!ADH:!EXP56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL 
  +# other SSL stuff
  +Alias /alesia "/var/tomcat/webapps/alesia"
  +
  +<Directory "/var/tomcat/webapps/alesia"> 
  +  <Directory "/var/tomcat/webapps/alesia"></Directory>
  +  <Directory "/var/tomcat/webapps/alesia">Options Indexes FollowSymLinks </Directory>
  +</Directory>
  +
  +JkMount /alesia/servlet/* ajp13
  +JkMount /alesia/*.jsp ajp13
  +
  +<Location "/alesia/WEB-INF/">
  +</Location>
  +
  +<Location "/alesia/WEB-INF/">
  +  AllowOverride None
  +  Deny from all
  +</Location>
  +
  +</VirtualHost>
  +
  +
+
-

SSL direct

-

If you want tomcat run HTTP/SSL, you need to create a SSL certificate. For - more informations about SSL and certificates, I suggest you could take a look - at OpenSSL (OpenSource SSL implementation) - and ModSSL (SSL support for Apache)

-

Verify tomcat server.xml configuration file

+ +

Direct SSL

+ +

If you want tomcat to serve HTTP/SSL (https) directly, you need to + create a SSL certificate. For more information about SSL and + certificates, I suggest you could take a look at OpenSSL (Open Source SSL + implementation) and mod_ssl (SSL + support for Apache)

+ +

Verify tomcat server.xml configuration + file

+

To use the HTTP with SSL connector in tomcat, verify that it is activated in server.xml

-

<Connector className="org.apache.tomcat.service.PoolTcpConnector">
- <Parameter name="handler" value="org.apache.tomcat.service.http.HttpConnectionHandler"/>
- <Parameter name="port" value="8443"/>
- <Parameter name="socketFactory" value="org.apache.tomcat.net.SSLSocketFactory" - />
- <Parameter name="keystore" value="/var/tomcat/conf/keystore" />
-
- <Parameter name="keypass" value="changeit"/>
- <Parameter name="clientAuth" value="true"/>
- </Connector>

-

In this example we indicate the keystore is file /var/tomcat/conf/keystore. - The keystore password is changeit and we want client to authentificate.

-
 
+ +
<Connector className="org.apache.tomcat.service.PoolTcpConnector">
  +<Parameter name="handler" value="org.apache.tomcat.service.http.HttpConnectionHandler"/>
  +<Parameter name="port" value="8443"/>
  +<Parameter name="socketFactory" value="org.apache.tomcat.net.SSLSocketFactory"/>
  +<Parameter name="keystore" value="/var/tomcat/conf/keystore" />
  +<Parameter name="keypass" value="changeit"/>
  +<Parameter name="clientAuth" value="true"/>
  +</Connector>
  +
+ +

In this example we indicate the keystore is file + /var/tomcat/conf/keystore. + The keystore password is changeit and we want + clients to authentificate.

+

Generate a SSL certificate (RSA) for tomcat

+
-

I succeed (at least) with my IBM JDK 1.3 after :

+

I succeed (at least) with my IBM JDK 1.3 after:

+ -

 

+

Importing SSL certificates

-

It's possible to import certificates generated with OpenSSL. - Here are the steps needed to generate such certs with OpenSSL :

+ +

It's possible to import certificates generated with OpenSSL. Here are the steps needed + to generate such certs with OpenSSL:

+ +
+

Credits

+

This document was created by Gomez Henri. Thanks to hgopal@cmcltd.com for import info. Feel free to contact me for more updates.

+
@@ -265,6 +317,7 @@
+ 1.2.2.3 +50 -44 jakarta-tomcat/src/doc/tomcat-apache-howto.html Index: tomcat-apache-howto.html =================================================================== RCS file: /home/cvs/jakarta-tomcat/src/doc/tomcat-apache-howto.html,v retrieving revision 1.2.2.2 retrieving revision 1.2.2.3 diff -u -r1.2.2.2 -r1.2.2.3 --- tomcat-apache-howto.html 2000/10/05 06:37:52 1.2.2.2 +++ tomcat-apache-howto.html 2001/02/01 16:52:21 1.2.2.3 @@ -1,6 +1,7 @@ + - + @@ -141,19 +142,22 @@

How will they work together?

-

In a nutshell a web server is waiting for requests.  When these requests arrive the server does whatever is needed to +

In a nutshell a web server is waiting for requests.  When + these requests arrive the server does whatever is needed to serve the requests by providing the necessary content.  Adding Tomcat to the mix may somewhat change this behavior.  Now the web server needs to perform the following:

We'd like Apache to handle our static content, such as - images and html documents, and to forward all requests for + images and HTML documents, and forward all requests for dynamic content to Tomcat.  More specifically, we need answers to the following questions:

@@ -227,14 +231,18 @@

-

<servlet>
-     <servlet-name>SlifkaWorld</servlet-name>
-     <servlet-class>foo.bar.baz.SomeClass</servlet-class>
-     <init-param>
-         <param-name>someParameter</param-name>
-         <param-value>A value</param-value>
-     </init-param>
- </servlet> +

<servlet>
+     + <servlet-name>SlifkaWorld</servlet-name>
+     + <servlet-class>foo.bar.baz.SomeClass</servlet-class>
+     <init-param>
+         + <param-name>someParameter</param-name>
+         + <param-value>A value</param-value>
+     </init-param>
+ </servlet>

@@ -327,13 +335,15 @@

<!-- Apache AJP12 support. This is also used to shut down tomcat. - -->
- <Connector className="org.apache.tomcat.service.PoolTcpConnector">
+ -->
+ <Connector + className="org.apache.tomcat.service.PoolTcpConnector">
    <Parameter name="handler"
-      value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/>
+      + value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/>
    <Parameter name="port"
-      value="8007"/>
- </Connector>

+      value="8007"/>
+ </Connector>

To ensure that it is indeed listening on that port, Telnet to it or @@ -541,7 +551,6 @@

For now, refer to the comments in the mod_jk.conf-auto file and mod_jk HOWTO for details.

-

tomcat-apache.conf @@ -786,15 +795,15 @@ following snippet from server.xml in our AJP section:

<!-- Apache AJP12 support. This is also used to shut down tomcat. - -->
+ --<
<Connector className="org.apache.tomcat.service.PoolTcpConnector">
    <Parameter name="handler" 
               - value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/>
+ value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/>
    <Parameter name="port"
               - value="8007"/>
- </Connector>

+ value="8007"/>
+ </Connector>

The key here is that each port parameter's "value" attribute must have a different value.  To keep in sync, let's @@ -1094,13 +1103,13 @@ 8080.  If you examine the supplied server.xml file, you'll see the following element:

-

<!-- Normal HTTP -->
+

<!-- Normal HTTP -->
<Connector className="org.apache.tomcat.service.PoolTcpConnector">
    <Parameter name="handler" 
        value="org.apache.tomcat.service.http.HttpConnectionHandler"/>
    <Parameter name="port" 
-         value="8080"/>
- </Connector>

+         value="8080"/>
+ </Connector>

To disable this, just comment out the entire <Connector> element.  Otherwise, just change it to a port that doesn't conflict @@ -1201,28 +1210,25 @@ to Apache/Tomcat

-

Tomcat doesn't support JSSI Until someone writes an Interceptor to +

Tomcat doesn't support JSSI. Until someone writes an Interceptor to handle them, the easiest way is to convert your .jhtml files to .jsp files.  Just replace:

-
-

<servlet name=myServlet>
+

<servlet name=myServlet>
    <param name=aParam value=aValue>
- </servlet>

+ </servlet>

-

with

-
-

<jsp:include page="/servlet/myServlet" +

<jsp:include page="/servlet/myServlet" flush="true" >
-    
<jsp:param name="aParam" +     <jsp:param name="aParam" value="aValue" />
- </jsp:include>

+ </jsp:include>

-

mod_rewrite - Used to work fine with Apache/JServ, what gives? @@ -1306,14 +1312,14 @@ off into a separate document and revised by Rob Slifka and Mike Bremford.  Contributors, listed in alphabetical order:
    - Jonathan Bnayahu
    - Mike Bremford
    - Alex Chaffee
    - Fiona Czuczman
    - Costin Manolache
    - Craig R. McClanahan
    - Rob Slifka
    - ...the countless many on the tomcat-dev and tomcat-user lists! +
  • Jonathan Bnayahu
    +
  • Mike Bremford
    +
  • Alex Chaffee
    +
  • Fiona Czuczman
    +
  • Costin Manolache
    +
  • Chris Pepper
    +
  • Rob Slifka
    +
  • ...the countless many on the tomcat-dev and tomcat-user lists!
No revision No revision 1.8.2.4 +164 -134 jakarta-tomcat/src/doc/uguide/Attic/tomcat_ug.html Index: tomcat_ug.html =================================================================== RCS file: /home/cvs/jakarta-tomcat/src/doc/uguide/Attic/tomcat_ug.html,v retrieving revision 1.8.2.3 retrieving revision 1.8.2.4 diff -u -r1.8.2.3 -r1.8.2.4 --- tomcat_ug.html 2000/10/16 02:12:20 1.8.2.3 +++ tomcat_ug.html 2001/02/01 16:52:24 1.8.2.4 @@ -1,7 +1,7 @@ - + - + @@ -11,12 +11,13 @@ +

- The Jakarta Project

Tomcat - A Minimalistic User's Guide

+

This document provides some basic information about Tomcat. Some of - the topics covered here are: + the topics covered here are:

  1. The installation of the Tomcat binary version.
  2. @@ -44,7 +46,7 @@
  3. An explanation on how to deploy Tomcat on a real web site.
- Hopefully this should be enough for any new user to get started +

Hopefully this should be enough for any new user to get started with Tomcat. If something is missing then try (in this order):

  1. Search the Tomcat faq.
  2. @@ -130,19 +132,21 @@ http://jakarta.apache.org/downloads/binindex.html. -
  3. Unzip the file into some directory (say foo). This - should create a new subdirectory named "tomcat". +
  4. Unpack the file into some directory (say foo). This + should create a new subdirectory named "jakarta-tomcat-3.2.1". + If it's not where you want it, move this directory to the desired + location. -
  5. Change directory to "tomcat" and set a new environment +
  6. Change directory to "jakarta-tomcat-3.2.1" and set a new environment variable (TOMCAT_HOME) to point to the root directory of your Tomcat hierarchy.
    1. On Win32 you should type:
      - "set TOMCAT_HOME=foo\tomcat"
    2. + "set TOMCAT_HOME=foo\jakarta-tomcat-3.2.1"
    3. On UNIX you should type:
      - for bash/sh "TOMCAT_HOME=foo/tomcat ; export TOMCAT_HOME"
      - for tcsh "setenv TOMCAT_HOME foo/tomcat"
    4. + for bash/sh "TOMCAT_HOME=foo/jakarta-tomcat-3.2.1 ; export TOMCAT_HOME"
      + for tcsh "setenv TOMCAT_HOME foo/jakarta-tomcat-3.2.1"
  7. Set the environment variable JAVA_HOME to point to the root @@ -170,9 +174,9 @@

    The Tomcat directory structure

    -

    Assuming you unzipped/untared the Tomcat binary distribution +

    Assuming you unzipped/untarred the Tomcat binary distribution you should have the following directory structure:

    - +
    @@ -220,7 +224,7 @@

    Additionally you can, or Tomcat will, create the following directories:

    -
    Directory name Description
    +
    work Automatically generated by Tomcat, this is where Tomcat @@ -254,7 +258,7 @@

    What are these scripts? The following table presents the scripts that are most important for the common user:

    - +
    @@ -284,7 +288,7 @@ A closer look at tomcat.sh/tomcat.bat yields that it performs the following actions:

    -
    Script name Description
    +
    @@ -322,8 +326,8 @@

    For example, if server.xml is located in /etc/server_1.xml and the user wants to start Tomcat in the background, they should - provide the following command line: -

    bin/tomcat.sh start -f /etc/server_1.xml

    + provide the following command line:

    +
    bin/tomcat.sh start -f /etc/server_1.xml
    @@ -361,8 +365,8 @@

    For example, if server.xml is located in conf\server_1.xml and the user wants to start Tomcat in a new window, they should - provide the following command line: -

    bin\tomcat.bat start -f conf\server_1.xml

    + provide the following command line:

    +
    bin\tomcat.bat start -f conf\server_1.xml
  8. Restores previously saved TOMCAT_HOME and CLASSPATH settings.
  9. @@ -372,7 +376,7 @@

    As you can see, the Win32 version of tomcat.bat is not as robust as the Unix one. Especially, it does not guess the values of JAVA_HOME and only tries - "." as a quess for TOMCAT_HOME. It can build CLASSPATH dynamically, but + "." as a guess for TOMCAT_HOME. It can build CLASSPATH dynamically, but not in all cases. It can not build CLASSPATH dynamically if TOMCAT_HOME contains spaces, or on Win9x, if TOMCAT_HOME contains non-8.3 directory names.

    @@ -384,10 +388,11 @@
  10. web.xml - Configures the various contexts in Tomcat.
  11. - This section will deal with how to use these files. We are not going to cover the internals - of web.xml, these internals are covered in depth in the Servlet APIs spec. Instead we will - cover the content of server.xml and discuss the usage of web.xml in the context of Tomcat. -

    +

    This section will deal with how to use these files. We are not + going to cover the internals of web.xml, these internals are + covered in depth in the Servlet APIs spec. Instead we will cover + the content of server.xml and discuss the usage of web.xml in the + context of Tomcat.

    server.xml

    server.xml is Tomcat's main configuration file. It serves two goals: @@ -398,7 +403,7 @@ server.xml. The important elements in server.xml are described in the following table: -

    Operating System Actions
    +
    @@ -436,7 +441,7 @@ - +
    Element Description
    ContextInterceptor & RequestInterceptor ContextInterceptor & RequestInterceptor These interceptors listen for certain events that happen in the ContextManager. For example, the ContextInterceptor listens for startup and shutdown events of Tomcat, and the RequestInterceptor @@ -488,16 +493,19 @@

    - Additional information may be found within the server.xml file. -

    + +

    Additional information may be found within the server.xml file.

    +

    Starting Tomcat From Another Directory

    By default tomcat will use TOMCAT_HOME/conf/server.xml for configuration. The default - configuration will use TOMCAT_HOME as it's base for the contexts.

    + configuration will use TOMCAT_HOME as it's base for the contexts.

    +

    You can change this by using the "-f /path/to/server.xml" option, with a different server configuration file and setting the home property of the context manger. You need to set up the required files inside the - home:

    + home:

    +
    • A webapps/ directory (if you created one) - all war files will be expanded and all subdirectories added as contexts.
    • @@ -556,11 +564,13 @@

      Web Server Operation

      -

      In a nutshell a web server is waiting for client HTTP requests. + +

      In a nutshell a web server is waiting for client HTTP requests. When these requests arrive the server does whatever is needed to serve the requests by providing the necessary content. Adding a servlet container may somewhat change this behavior. Now the web - server needs also to perform the following: + server needs also to perform the following:

      +
      • Load the servlet container adapter library and initialize it (prior to serving requests).
      • @@ -569,10 +579,9 @@ take the request and handle it.
      - The adapter on the other hand needs to know what requests it is +

      The adapter on the other hand needs to know what requests it is going to serve, usually based on some pattern in the request URL, and to - where to direct these requests. -

      + where to direct these requests.

      Things are even more complex when the user wants to set a configuration @@ -582,11 +591,12 @@

      What is the Needed Configuration

      -

      The most obvious configuration that one can think of is the identity of the servlet URLs + +

      The most obvious configuration that one can think of is the identity of the servlet URLs that are under the responsibility of the servlet container. This is clear; someone must know what requests to transmit to the servlet container... Yet there are additional configuration items that we should provide to - the web-server/servlet-container combination: + the web-server/servlet-container combination:

      • We also need to provide configuration regarding the available Tomcat processes and on which TCP/IP host/port they are listening.
      • @@ -594,10 +604,10 @@ will be able to load it on startup).
      • We need to set adapter internal information such as where and how much to log, etc.
      - All this information must appear either in the web server configuration, or in a private + +

      All this information must appear either in the web server configuration, or in a private configuration files used by the adapter. The next section will demonstrate how configuration - can be implemented on Apache. -

      + can be implemented on Apache.

      Making it on Apache

      @@ -630,7 +640,8 @@

      The Apache-Tomcat configuration uses Apache core configuration directives as well as Jserv unique directives so it may confuse you at first, there are - however two things simplifying it: + however two things simplifying it:

      +
      • In general you can distinguish between the two directive "families" by noting that all the Jserv unique directives start @@ -640,8 +651,9 @@ generated tomcat-apache.conf, so you can look at a single file.
      - Lets look now at a sample tomcat.conf file. -

      + +

      Let's look now at a sample tomcat.conf file.

      +
      -

      +

      As you can see the configuration process was split into 4 steps - that will now be explained: + that will now be explained:

      +
      1. In this step we instruct Apache to load the jserv shared-object (or the NT world dll). This is a well known Apache @@ -727,26 +740,33 @@ ApJServMount example is a rather simple one, in fact ApJServMount can also provide information regarding the communication protocol to be used and the location where the Tomcat process listens, for example: +
        ApJServMount /examples ajpv12://hostname:port/root
        + mounts the context /examples to a Tomcat process that runs on host "hostname" and listens on port number "port".
      - Now that you understand the different configuration instructions in the sample + +

      Now that you understand the different configuration instructions in the sample file, how can you add it to the Apache configuration? One "simple" method is to - write it's content in the httpd.conf (the Apache configuration file), this however + write its content in the httpd.conf (the Apache configuration file), this however can be very messy. Instead you should use the Apache include directive. At the end - of the Apache configuration file (httpd.conf) add the following directive: + of the Apache configuration file (httpd.conf) add the following directive:

      +
      include <full path to the Tomcat configuration file>
      - for example: -
      include /tome/tomcat/conf/tomcat.conf
      This - will add your Tomcat configuration to Apache, after that you should copy - the jserv module to the Apache libexec (or modules in the Win32 case) - directory and restart (stop+start) Apache. It should now be able to - connect to Tomcat. -

      + +

      for example:

      + +
      include /tome/tomcat/conf/tomcat.conf
      + +

      This will add your Tomcat configuration to Apache, after that + you should copy the jserv module to the Apache libexec (or modules + in the Win32 case) directory and restart (stop+start) Apache. It + should now be able to connect to Tomcat.

      Obtaining the Jserv Module (mod_jserv)

      +

      As previously stated, we need a web server adapter to sit in Apache and redirect requests to Tomcat. For Apache, this adapter is a slightly modified version of mod_jserv. @@ -797,9 +817,11 @@

    - That's it; you have built mod_jserv... -

    + +

    That's it; you have built mod_jserv...

    +

    Making Apache Serve your Context's Static Files

    +

    The previous Apache-Tomcat configuration file was somewhat inefficient, it instructed Apache to send any request for a resource that starts with the /examples prefix to be served by @@ -814,19 +836,20 @@

  12. You may want to follow users requests for static resources using interceptors.
  13. - In general however, this is not that case; and making Tomcat save + +

    In general however, this is not that case; and making Tomcat save static files is just a CPU waste. We should instead have Apache serve - these static files and not Tomcat. Lets look now at a sample - tomcat.conf file that does exactly that: -

    -

    Having Apache serve the static files requires the following: + these static files and not Tomcat.

    + +

    Having Apache serve the static files requires the following:

    1. Instructing Apache to send all servlet requests to Tomcat.
    2. Instructing Apache to send all JSP requests to Tomcat.
    - and leaving Apache to handle the rest. Lets look now at a sample - tomcat.conf file that does exactly that: -

    + +

    and leaving Apache to handle the rest. Let's look now at a sample + tomcat.conf file that does exactly that:

    +
    -

    As you can see, the beginning of this configuration file is the same @@ -915,26 +937,28 @@ context to Tomcat. - It is easy to see that this configuration is much more complex and +

    It is easy to see that this configuration is much more complex and error prone then the first example, this however is the price that you - should (for now) pay for improved performance. -

    + should (for now) pay for improved performance.

    -

    Configuring for Multiple Tomcat JVMs

    +

    Configuring for Multiple Tomcat JVMs

    +

    Sometimes it is useful to have different contexts handled by - different JVMs, for example: + different JVMs, for example:

    +
    • When each context serves a different, specific task and runs on a different machine.
    • When we want to have multiple developers work on a private Tomcat process but use the same web server.
    - Implementing such schemes where different contexts are served by + +

    Implementing such schemes where different contexts are served by different JVMs is very easy and the following configuration file demonstrates this:

    -

    +
    -

    +

    - As you can see in the previous example, using several JVMs (even even + As you can see in the previous example, using several JVMs (even those that run on different machines) can be accomplished easily by using a full ajp URL mount. In this full URL we actually specify the host where the Tomcat process is located and it's port. @@ -1174,14 +1198,16 @@

    Then we should start the two tomcat processes using the -f command - line option: -

    bin\starup -f conf\server_joe.xml
    -
    bin\starup -f conf\server_bill.xml
    - and then access them from Apache based on the different URL path - prefixes. -

    + line option:

    +
    bin\startup -f conf\server_joe.xml
    +
    bin\startup -f conf\server_bill.xml
    + +

    and then access them from Apache based on the different URL path + prefixes.

    +

    Configuring Virtual Hosting

    +

    It is possible to support virtual hosts under Tomcat Ver3.2, in fact the virtual host configuration is very similar to configuring for @@ -1192,7 +1218,7 @@

    With the current (Ver3.2) Tomcat, virtual hosting awareness is - provided by the web server (Apache/Netscape…). The web server + provided by the web server (Apache/Netscape). The web server virtual hosting support is used by the Tomcat adapter to redirect requests belonging to a certain virtual host to the JVM(s) containing the contexts of this virtual host. This means that if (for @@ -1205,7 +1231,6 @@ Apache-Tomcat configuration file:

    -

    -

    As can be seen, steps 1,2 and 3 define two Apache virtual hosts and @@ -1283,10 +1307,11 @@

    Modify and Customize the Batch Files

    -

    - As stated in the previous sections, the startup scripts are here for + +

    As stated in the previous sections, the startup scripts are here for your convenient. Yet, sometimes the scripts that are needed for - deployment should be modified: + deployment should be modified:

    +
    • To set resource limits such as maximum number of descriptors.
    • @@ -1301,7 +1326,7 @@
    • Your pet reason.
    - Some of these changes can be done without explicit changes to +

    Some of these changes can be done without explicit changes to the basic scripts; for example, the tomcat script can use an environment variable named TOMCAT_OPTS to set extra command line parameters to the JVM (such as memory setting etc.). @@ -1310,14 +1335,17 @@ as PATH, JAVA_HOME, TOMCAT_HOME and CLASSPATH from this file. On NT however (and also on UNIX when the modifications are for something such as the JVM command line) you are forced to rewrite some of the - startup script...

    Do not hesitate, just do it.
    -

    + startup script...

    + +
    Do not hesitate, just do it.
    +

    Modify the Default JVM Settings

    -

    - The default JVM settings in the tomcat script are very naïve; + +

    The default JVM settings in the tomcat script are very naïve; everything is left for defaults. There are a few things that you - should consider to improve your Tomcat performance: + should consider to improve your Tomcat performance:

    +
    1. Modify your JVM memory configuration. Normally the JVM allocates an initial size for the Java heap and that's it, if @@ -1346,15 +1374,13 @@ and make a calculated decision.
    -

    Modify your Connectors

    -

    - The Connectors, as configured in Tomcat's default server.xml + +

    The Connectors, as configured in Tomcat's default server.xml contains two Connectors configured as in the next server.xml - fragment: + fragment:

    -

    -

    1. Is a Connector that listens on port 8080 for incoming HTTP @@ -1395,16 +1420,16 @@ integration (out-of-process servlet integration).
    - The AJPV12 Connector is required for Tomcat shutdown. However, the - HTTP Connector may be removed if stand-alone operation is not needed. -

    +

    The AJPV12 Connector is required for Tomcat shutdown. However, the + HTTP Connector may be removed if stand-alone operation is not needed.

    +

    Use a Thread Pool in your Connectors

    -

    - Tomcat is a multi-threaded servlet container this means that each +

    Tomcat is a multi-threaded servlet container this means that each request needs to be executed by some thread. Prior to Tomcat 3.2, the default was to create a new thread to serve each request that arrives. This behavior is problematic for loaded sites - because: + because:

    +
    • Starting and stopping a thread for every request puts a needless burden on the operating system and the JVM.
    • @@ -1416,14 +1441,16 @@ Descriptors...) than it should and it can lead to low performance and even crashes if resources are exhausted.
    - The solution for these problems is to use a thread pool, which + +

    The solution for these problems is to use a thread pool, which is the default for Tomcat 3.2. Servlet containers that are using a thread pool relieve themselves from directly managing their threads. Instead of allocating new threads; whenever they need a thread they ask for it from the pool, and when they are done, the thread is returned to the pool. The thread pool can now be used to implement sophisticated thread - management techniques, such as: + management techniques, such as:

    +
    1. Keeping threads "open" and reusing them over and over again. This saves the trouble associated with creating and @@ -1444,19 +1471,17 @@
    - You can refine the techniques described above in various ways, but + +

    You can refine the techniques described above in various ways, but these are only refinements. The main contribution of thread pools is thread-reuse and having a concurrency upper bound that limits - resource usage. -

    + resource usage.

    -

    - Using a thread pool in Tomcat is a simple move; all you need to do +

    Using a thread pool in Tomcat is a simple move; all you need to do is to use a PoolTcpConnector in your <Connector> configuration. For example the following server.xml fragment defines - ajpv12, pooled Connector: + ajpv12, pooled Connector:

    -

    -

    - This fragment is very simple and the (default) pool behaviour - instructed by it is: +

    This fragment is very simple and the (default) pool behaviour + instructed by it is:

    +
    • Upper bound for concurrency of 50 threads.
    • When the pool has more then 25 threads standing idle it @@ -1492,12 +1517,13 @@ to keep 10 vacant threads (as long as the upper bound is kept).
    - The default configuration is suitable for medium load sites with an + +

    The default configuration is suitable for medium load sites with an average of 10-40 concurrent requests. If your site differs you should modify this configuration (for example reduce the upper limit). Configuring the pool can be done through the <Connector> - element in server.xml as demonstrated in the next fragment: -

    + element in server.xml as demonstrated in the next fragment:

    +
    -

    - As can be seen the pool has 3 configuration parameters: + +

    As can be seen the pool has 3 configuration parameters:

    +
    • max_threads - defines the upper bound to the for the concurrency, the pool will not create more then this number @@ -1546,10 +1573,10 @@ be bigger then 0.
    - You should use the above parameters to adjust the pool behavior to - your needs. -

    +

    You should use the above parameters to adjust the pool behavior to + your needs.

    +

    Disable Servlet Auto-Reloading

    Servlet auto-reloading is really useful for development time. @@ -1564,18 +1591,21 @@

    Authors

    -

    - This document was created by: +

    This document was created by:

    + - With help from (alphabetical ordered): + +

    With help from (alphabetical ordered):

    +
      - Jonathan Bnayahu
      - Fiona Czuczman
      - Costin Manolache
      +
    • Jonathan Bnayahu +
    • Fiona Czuczman +
    • Costin Manolache +
    • Chris Pepper
    -

    +