You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by cr...@apache.org on 2001/11/12 22:03:49 UTC

cvs commit: jakarta-tomcat-4.0/webapps/tomcat-docs class-loader-howto.xml introduction.xml jndi-resources-howto.xml manager-howto.xml proxy-howto.xml realm-howto.xml ssl-howto.xml

craigmcc    01/11/12 13:03:49

  Modified:    webapps/tomcat-docs class-loader-howto.xml introduction.xml
                        jndi-resources-howto.xml manager-howto.xml
                        proxy-howto.xml realm-howto.xml ssl-howto.xml
  Log:
  Update line endings only (\r \n -> \n).  No content changes.
  
  Revision  Changes    Path
  1.3       +210 -210  jakarta-tomcat-4.0/webapps/tomcat-docs/class-loader-howto.xml
  
  Index: class-loader-howto.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/class-loader-howto.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- class-loader-howto.xml	2001/10/03 22:00:41	1.2
  +++ class-loader-howto.xml	2001/11/12 21:03:48	1.3
  @@ -1,210 +1,210 @@
  -<?xml version="1.0"?>
  -<!DOCTYPE document [
  -  <!ENTITY project SYSTEM "project.xml">
  -]>
  -<document>
  -
  -    &project;
  -
  -    <properties>
  -        <author email="craigmcc@apache.org">Craig R. McClanahan</author>
  -        <title>Class Loader HOW-TO</title>
  -    </properties>
  -
  -<body>
  -
  -
  -<section name="Quick Start">
  -
  -<p>The following rules cover about 95% of the decisions that application
  -developers and deployers must make about where to place class and resource
  -files to make them available to web applications:</p>
  -<ul>
  -<li>For classes and resources specific to a particular web application,
  -    place unpacked classes and resources under <code>/WEB-INF/classe</code>
  -    of your web application archive, or place JAR files containing those
  -    classes and resources under <code>/WEB-INF/lib</code> of your web
  -    application archive.</li>
  -<li>For classes and resources that must be shared across all web applications,
  -    place unpacked classes and resources under
  -    <code>$CATALINA_HOME/shared/classes</code>, or place JAR files
  -    containing those classes and resources under
  -    <code>$CATALINA_HOME/shared/lib</code>.</li>
  -</ul>
  -
  -</section>
  -
  -
  -<section name="Overview">
  -
  -<p>Like many server applications, Tomcat 4 installs a variety of class loaders
  -(that is, classes that implement <code>java.lang.ClassLoader</code>) to allow
  -different portions of the container, and the web applications running on the
  -container, to have access to different repositories of available classes and
  -resources.  This mechanism is used to provide the functionality defined in the
  -Servlet Specification, version 2.3 -- in particular, Sections 9.4 and 9.6.</p>
  -
  -<p>In a Java 2 (that is, JDK 1.2 or later) environment, class loaders are
  -arranged in a parent-child tree.  Normally, when a class loader is asked to
  -load a particular class or resource, it delegates the request to a parent
  -class loader first, and then looks in its own repositories only if the parent
  -class loader(s) cannot find the requested class or resource.  The model for
  -web application class loaders differs slightly from this, as discussed below,
  -but the main principles are the same.</p>
  -
  -<p>When Tomcat 4 is started, it creates a set of class loaders that are
  -organized into the following parent-child relationships, where the parent
  -class loader is above the child class loader:</p>
  -
  -<source>
  -      Bootstrap
  -          |
  -       System
  -          |
  -       Common
  -      /      \
  - Catalina   Shared
  -             /   \
  -        Webapp1  Webapp2 ... 
  -</source>
  -
  -<p>The characteristics of each of these class loaders, including the source
  -of classes and resources that they make visible, are discussed in detail in
  -the following section.</p>
  -
  -</section>
  -
  -<section name="Class Loader Definitions">
  -
  -<p>As indicated in the diagram above, Tomcat 4 creates the following class
  -loaders as it is initialized:</p>
  -<ul>
  -<li><strong>Bootstrap</strong> - This class loader contains the basic runtime
  -    classes provided by the Java Virtual Machine, plus any classes from JAR
  -    files present in the System Extensions directory
  -    (<code>$JAVA_HOME/jre/lib/ext</code>).  <em>NOTE</em> - Some JVMs may
  -    implement this as more than one class loader, or it may not be visible
  -    (as a class loader) at all.</li>
  -<li><strong>System</strong> - This class loader is normally initialized from
  -    the contents of the <code>CLASSPATH</code> environment variable.  All such
  -    classes are visible to both Tomcat internal classes, and to web
  -    applications.  However, the standard Tomcat 4 startup scripts
  -    (<code>$CATALINA_HOME/bin/catalina.sh</code> or
  -    <code>%CATALINA_HOME%\bin\catalina.bat</code>) totally ignore the contents
  -    of the <code>CLASSPATH</code> environment variable itself, and instead
  -    build the System class loader from the following repositories:
  -    <ul>
  -    <li><em>$CATALINA_HOME/lib/bootstrap.jar</em> - Contains the main() method
  -        that is used to initialize the Tomcat 4 server, and the class loader
  -        implementation classes it depends on.</li>
  -    <li><em>$JAVA_HOME/lib/tools.jar</em> - Contains the "javac" compiler used
  -        to convert JSP pages into servlet classes.</li>
  -    </ul></li>
  -<li><strong>Common</strong> - This class loader contains additional classes
  -    that are made visible to both Tomcat internal classes and to all web
  -    applications.  Normally, application classes should <strong>NOT</strong>
  -    be placed here.  All unpacked classes and resources in
  -    <code>$CATALINA_HOME/common/classes</code>, as well as classes and
  -    resources in JAR files under
  -    <code>$CATALINA_HOME/common/lib</code>, are made visible through this
  -    class loader.  By default, that includes the following:
  -    <ul>
  -    <li><em>jndi.jar</em> - The Java Naming and Directory Interface API
  -        classes (loaded <strong>ONLY</strong> on a JDK 1.2 system, because they
  -        are included automatically on JDK 1.3 and later).</li>
  -    <li><em>naming-common.jar</em> - The JNDI implementation used by Tomcat 4
  -        to represent in-memory naming contexts.</li>
  -    <li><em>naming-resources.jar</em> - The specialized JNDI naming context
  -        implementation used to represent the static resources of a web
  -        application.</li>
  -    <li><em>servlet.jar</em> - The Servlet and JSP API classes.</li>
  -    <li><em>xerces.jar</em> - The XML parser that is visible by default to
  -        Tomcat internal classes and to web applications.  This can be
  -        overridden, for a particular web application, by including your
  -        desired parser in <code>/WEB-INF/lib</code>.</li>
  -    </ul></li>
  -<li><strong>Catalina</strong> - This class loader is initialized to include
  -    all classes and resources required to implement Tomcat 4 itself.  These
  -    classes and resources are <strong>TOTALLY</strong> invisible to web
  -    applications.  All unpacked classes and resources in
  -    <code>$CATALINA_HOME/server/classes</code>, as well as classes and
  -    resources in JAR files under
  -    <code>$CATALINA_HOME/server/lib</code>, are made visible through
  -    this class loader.  By default, that includes the following:
  -    <ul>
  -    <li><em>catalina.jar</em> - Implementation of the Catalina servlet
  -        container portion of Tomcat 4.</li>
  -    <li><em>jakarta-regexp-X.Y.jar</em> - The binary distribution of the
  -        <a href="http://jakarta.apache.org/regexp/">Jakarta Regexp</a>
  -        regular expression processing library, used in the implementation of
  -        request filters.</li>
  -    <li><em>servlets-xxxxx.jar</em> - The classes associated with each
  -        internal servlet that provides part of Tomcat's functionality.
  -        These are separated so that they can be completely removed if the
  -        corresponding service is not required, or they can be subject to
  -        specialized security manager permissions.</li>
  -    <li><em>tomcat-ajp.jar</em> - Classes for the Java portion of the
  -        <code>mod_jk</code> web server connector, which allows Tomcat to
  -        run behind web servers such as Apache and iPlanet iAS and iWS.</li>
  -    <li><em>tomcat-util.jar</em> - Utility classes required by
  -        <em>tomcat-ajp.jar</em>.</li>
  -    <li><em>warp.jar</em> - Classes for the Java portion of the
  -        <code>mod_webapp</code> web server connector, which allows Tomcat to
  -        run behind web servers such as Apache and iPlanet iAS and iWS.</li>
  -    </ul></li>
  -<li><strong>Shared</strong> - This class loader is the place to put classes
  -    and resources that you wish to share across <strong>ALL</strong>
  -    web applications (unless Tomcat internal classes also need access,
  -    in which case you should put them in the <strong>Common</strong>
  -    class loader instead).  All unpacked classes and resources in
  -    <code>$CATALINA_HOME/shared/classes</code>, as well as classes and
  -    resources in JAR files under <code>$CATALINA_HOME/lib</code>, are
  -    made visible through this class loader.  By default, that includes
  -    the following:
  -    <ul>
  -    <li><em>jasper-compiler.jar</em> - The page compiler classes required
  -        to convert JSP source pages into executable servlets and compile
  -        them.</li>
  -    <li><em>jasper-runtime.jar</em> - The runtime support classes required
  -        to execute JSP pages that have already been translated into Java
  -        servlets and then compiled.</li>
  -    <li><em>naming-factory.jar</em> - JNDI object factories for resources
  -        supported by the default JNDI naming context provided to web
  -        applications.</li>
  -    </ul></li>
  -<li><strong>WebappX</strong> - A class loader is created for each web
  -    application that is deployed in a single Tomcat 4 instance.  All unpacked
  -    classes and resources in the <code>/WEB-INF/classes</code> directory of
  -    your web application archive, plus classes and resources in JAR files
  -    under the <code>/WEB-INF/lib</code> directory of your web application
  -    archive, are made visible to the containing web application, but to
  -    no others.</li>
  -</ul>
  -
  -<p>As mentioned above, the web application class loader diverges from the
  -default Java 2 delegation model (in accordance with the recommendations in the
  -Servlet Specification, version 2.3, section 9.6).  When a request to load a
  -class from the web application's <em>WebappX</em> class loader is processed,
  -this class loader will look in the local repositories <strong>first</strong>,
  -instead of delegating before looking.  All other class loaders in Tomcat 4
  -follow the usual delegation pattern.</p>
  -
  -<p>Therefore, from the perspective of a web application, class or resource
  -loading looks in the following repositories, in this order:</p>
  -<ul>
  -<li><em>/WEB-INF/classes</em> of your web application</li>
  -<li><em>/WEB-INF/lib/*.jar</em> of your web application</li>
  -<li>Bootstrap classes of your JVM</li>
  -<li>System class loader classses (described above)</li>
  -<li><em>$CATALINA_HOME/common/classes</em></li>
  -<li><em>$CATALINA_HOME/common/*.jar</em></li>
  -<li><em>$CATALINA_HOME/shared/classes</em></li>
  -<li><em>$CATALINA_HOME/shared/lib/*.jar</em></li>
  -</ul>
  -
  -</section>
  -
  -
  -</body>
  -
  -</document>
  +<?xml version="1.0"?>
  +<!DOCTYPE document [
  +  <!ENTITY project SYSTEM "project.xml">
  +]>
  +<document>
  +
  +    &project;
  +
  +    <properties>
  +        <author email="craigmcc@apache.org">Craig R. McClanahan</author>
  +        <title>Class Loader HOW-TO</title>
  +    </properties>
  +
  +<body>
  +
  +
  +<section name="Quick Start">
  +
  +<p>The following rules cover about 95% of the decisions that application
  +developers and deployers must make about where to place class and resource
  +files to make them available to web applications:</p>
  +<ul>
  +<li>For classes and resources specific to a particular web application,
  +    place unpacked classes and resources under <code>/WEB-INF/classe</code>
  +    of your web application archive, or place JAR files containing those
  +    classes and resources under <code>/WEB-INF/lib</code> of your web
  +    application archive.</li>
  +<li>For classes and resources that must be shared across all web applications,
  +    place unpacked classes and resources under
  +    <code>$CATALINA_HOME/shared/classes</code>, or place JAR files
  +    containing those classes and resources under
  +    <code>$CATALINA_HOME/shared/lib</code>.</li>
  +</ul>
  +
  +</section>
  +
  +
  +<section name="Overview">
  +
  +<p>Like many server applications, Tomcat 4 installs a variety of class loaders
  +(that is, classes that implement <code>java.lang.ClassLoader</code>) to allow
  +different portions of the container, and the web applications running on the
  +container, to have access to different repositories of available classes and
  +resources.  This mechanism is used to provide the functionality defined in the
  +Servlet Specification, version 2.3 -- in particular, Sections 9.4 and 9.6.</p>
  +
  +<p>In a Java 2 (that is, JDK 1.2 or later) environment, class loaders are
  +arranged in a parent-child tree.  Normally, when a class loader is asked to
  +load a particular class or resource, it delegates the request to a parent
  +class loader first, and then looks in its own repositories only if the parent
  +class loader(s) cannot find the requested class or resource.  The model for
  +web application class loaders differs slightly from this, as discussed below,
  +but the main principles are the same.</p>
  +
  +<p>When Tomcat 4 is started, it creates a set of class loaders that are
  +organized into the following parent-child relationships, where the parent
  +class loader is above the child class loader:</p>
  +
  +<source>
  +      Bootstrap
  +          |
  +       System
  +          |
  +       Common
  +      /      \
  + Catalina   Shared
  +             /   \
  +        Webapp1  Webapp2 ... 
  +</source>
  +
  +<p>The characteristics of each of these class loaders, including the source
  +of classes and resources that they make visible, are discussed in detail in
  +the following section.</p>
  +
  +</section>
  +
  +<section name="Class Loader Definitions">
  +
  +<p>As indicated in the diagram above, Tomcat 4 creates the following class
  +loaders as it is initialized:</p>
  +<ul>
  +<li><strong>Bootstrap</strong> - This class loader contains the basic runtime
  +    classes provided by the Java Virtual Machine, plus any classes from JAR
  +    files present in the System Extensions directory
  +    (<code>$JAVA_HOME/jre/lib/ext</code>).  <em>NOTE</em> - Some JVMs may
  +    implement this as more than one class loader, or it may not be visible
  +    (as a class loader) at all.</li>
  +<li><strong>System</strong> - This class loader is normally initialized from
  +    the contents of the <code>CLASSPATH</code> environment variable.  All such
  +    classes are visible to both Tomcat internal classes, and to web
  +    applications.  However, the standard Tomcat 4 startup scripts
  +    (<code>$CATALINA_HOME/bin/catalina.sh</code> or
  +    <code>%CATALINA_HOME%\bin\catalina.bat</code>) totally ignore the contents
  +    of the <code>CLASSPATH</code> environment variable itself, and instead
  +    build the System class loader from the following repositories:
  +    <ul>
  +    <li><em>$CATALINA_HOME/lib/bootstrap.jar</em> - Contains the main() method
  +        that is used to initialize the Tomcat 4 server, and the class loader
  +        implementation classes it depends on.</li>
  +    <li><em>$JAVA_HOME/lib/tools.jar</em> - Contains the "javac" compiler used
  +        to convert JSP pages into servlet classes.</li>
  +    </ul></li>
  +<li><strong>Common</strong> - This class loader contains additional classes
  +    that are made visible to both Tomcat internal classes and to all web
  +    applications.  Normally, application classes should <strong>NOT</strong>
  +    be placed here.  All unpacked classes and resources in
  +    <code>$CATALINA_HOME/common/classes</code>, as well as classes and
  +    resources in JAR files under
  +    <code>$CATALINA_HOME/common/lib</code>, are made visible through this
  +    class loader.  By default, that includes the following:
  +    <ul>
  +    <li><em>jndi.jar</em> - The Java Naming and Directory Interface API
  +        classes (loaded <strong>ONLY</strong> on a JDK 1.2 system, because they
  +        are included automatically on JDK 1.3 and later).</li>
  +    <li><em>naming-common.jar</em> - The JNDI implementation used by Tomcat 4
  +        to represent in-memory naming contexts.</li>
  +    <li><em>naming-resources.jar</em> - The specialized JNDI naming context
  +        implementation used to represent the static resources of a web
  +        application.</li>
  +    <li><em>servlet.jar</em> - The Servlet and JSP API classes.</li>
  +    <li><em>xerces.jar</em> - The XML parser that is visible by default to
  +        Tomcat internal classes and to web applications.  This can be
  +        overridden, for a particular web application, by including your
  +        desired parser in <code>/WEB-INF/lib</code>.</li>
  +    </ul></li>
  +<li><strong>Catalina</strong> - This class loader is initialized to include
  +    all classes and resources required to implement Tomcat 4 itself.  These
  +    classes and resources are <strong>TOTALLY</strong> invisible to web
  +    applications.  All unpacked classes and resources in
  +    <code>$CATALINA_HOME/server/classes</code>, as well as classes and
  +    resources in JAR files under
  +    <code>$CATALINA_HOME/server/lib</code>, are made visible through
  +    this class loader.  By default, that includes the following:
  +    <ul>
  +    <li><em>catalina.jar</em> - Implementation of the Catalina servlet
  +        container portion of Tomcat 4.</li>
  +    <li><em>jakarta-regexp-X.Y.jar</em> - The binary distribution of the
  +        <a href="http://jakarta.apache.org/regexp/">Jakarta Regexp</a>
  +        regular expression processing library, used in the implementation of
  +        request filters.</li>
  +    <li><em>servlets-xxxxx.jar</em> - The classes associated with each
  +        internal servlet that provides part of Tomcat's functionality.
  +        These are separated so that they can be completely removed if the
  +        corresponding service is not required, or they can be subject to
  +        specialized security manager permissions.</li>
  +    <li><em>tomcat-ajp.jar</em> - Classes for the Java portion of the
  +        <code>mod_jk</code> web server connector, which allows Tomcat to
  +        run behind web servers such as Apache and iPlanet iAS and iWS.</li>
  +    <li><em>tomcat-util.jar</em> - Utility classes required by
  +        <em>tomcat-ajp.jar</em>.</li>
  +    <li><em>warp.jar</em> - Classes for the Java portion of the
  +        <code>mod_webapp</code> web server connector, which allows Tomcat to
  +        run behind web servers such as Apache and iPlanet iAS and iWS.</li>
  +    </ul></li>
  +<li><strong>Shared</strong> - This class loader is the place to put classes
  +    and resources that you wish to share across <strong>ALL</strong>
  +    web applications (unless Tomcat internal classes also need access,
  +    in which case you should put them in the <strong>Common</strong>
  +    class loader instead).  All unpacked classes and resources in
  +    <code>$CATALINA_HOME/shared/classes</code>, as well as classes and
  +    resources in JAR files under <code>$CATALINA_HOME/lib</code>, are
  +    made visible through this class loader.  By default, that includes
  +    the following:
  +    <ul>
  +    <li><em>jasper-compiler.jar</em> - The page compiler classes required
  +        to convert JSP source pages into executable servlets and compile
  +        them.</li>
  +    <li><em>jasper-runtime.jar</em> - The runtime support classes required
  +        to execute JSP pages that have already been translated into Java
  +        servlets and then compiled.</li>
  +    <li><em>naming-factory.jar</em> - JNDI object factories for resources
  +        supported by the default JNDI naming context provided to web
  +        applications.</li>
  +    </ul></li>
  +<li><strong>WebappX</strong> - A class loader is created for each web
  +    application that is deployed in a single Tomcat 4 instance.  All unpacked
  +    classes and resources in the <code>/WEB-INF/classes</code> directory of
  +    your web application archive, plus classes and resources in JAR files
  +    under the <code>/WEB-INF/lib</code> directory of your web application
  +    archive, are made visible to the containing web application, but to
  +    no others.</li>
  +</ul>
  +
  +<p>As mentioned above, the web application class loader diverges from the
  +default Java 2 delegation model (in accordance with the recommendations in the
  +Servlet Specification, version 2.3, section 9.6).  When a request to load a
  +class from the web application's <em>WebappX</em> class loader is processed,
  +this class loader will look in the local repositories <strong>first</strong>,
  +instead of delegating before looking.  All other class loaders in Tomcat 4
  +follow the usual delegation pattern.</p>
  +
  +<p>Therefore, from the perspective of a web application, class or resource
  +loading looks in the following repositories, in this order:</p>
  +<ul>
  +<li><em>/WEB-INF/classes</em> of your web application</li>
  +<li><em>/WEB-INF/lib/*.jar</em> of your web application</li>
  +<li>Bootstrap classes of your JVM</li>
  +<li>System class loader classses (described above)</li>
  +<li><em>$CATALINA_HOME/common/classes</em></li>
  +<li><em>$CATALINA_HOME/common/*.jar</em></li>
  +<li><em>$CATALINA_HOME/shared/classes</em></li>
  +<li><em>$CATALINA_HOME/shared/lib/*.jar</em></li>
  +</ul>
  +
  +</section>
  +
  +
  +</body>
  +
  +</document>
  
  
  
  1.2       +132 -132  jakarta-tomcat-4.0/webapps/tomcat-docs/introduction.xml
  
  Index: introduction.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/introduction.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- introduction.xml	2001/08/06 20:24:07	1.1
  +++ introduction.xml	2001/11/12 21:03:49	1.2
  @@ -1,132 +1,132 @@
  -<?xml version="1.0"?>
  -<!DOCTYPE document [
  -  <!ENTITY project SYSTEM "project.xml">
  -]>
  -<document>
  -
  -    &project;
  -
  -    <properties>
  -        <author email="rslifka@sfu.ca">Robert Slifka</author>
  -        <title>Introduction</title>
  -    </properties>
  -
  -<body>
  -
  -
  -<section name="Introduction">
  -
  -<p>For administrators and web developers alike, there are some important bits
  -of information you should familiarize yourself with before starting out. This
  -document serves as a brief introduction to some of the concepts and
  -terminology behind the Tomcat container. As well, where to go when you need
  -help.</p>
  -
  -</section>
  -
  -
  -<section name="Terminology">
  -
  -<p>In the course of reading these documents, you'll run across a number of
  -terms; some specific to Tomcat, and others defined by the
  -<a href="http://java.sun.com/products/servlet/">Servlet</a> or
  -<a href="http://java.sun.com/products/jsp/">JSP</a> specifications.</p>
  -
  -<ul>
  -<li><strong>Context</strong> - In a nutshell, a Context is a
  -    web application.</li>
  -<li><strong>Term2</strong> - This is it.</li>
  -<li><strong>Term3</strong> - This is it!</li>
  -</ul>
  -
  -</section>
  -
  -
  -<section name="Directories and Files">
  -
  -<p>Throughout the docs, you'll notice there are numerous references to
  -<strong>$CATALINA_HOME</strong>. This represents the root of your Tomcat
  -installation. When we say, "This information can be found in your
  -$CATALINA_HOME/README.txt file" we mean to look at the README.txt file at the
  -root of your Tomcat install.</p>
  -
  -<p>For the complete description of the Tomcat distribution, each folder can be
  -found in the <a href="README.txt">README.txt</a> file, residing in the root
  -directory of your Tomcat installation. Here, we will cover the ones where
  -you'll be spending the majority of your time.</p>
  -
  -<ul>
  -<li><strong>/bin</strong> - Startup, shutdown, and other scripts. The
  -    <code>*.sh</code> files (for Unix systems) are functional duplicates of
  -    the <code>*.bat</code> files (for Windows systems).  Since the Win32
  -    command-line lacks certain functionality, there are some additional
  -    files in here.</li>
  -<li><strong>/conf</strong> - Configuration files and related DTDs.  The most
  -    important file in here is server.xml.  It is the main configuration file
  -    for the container.</li>
  -<li><strong>/logs</strong> - Log files are here by default.</li>
  -<li><strong>/webapps</strong> - This is where your webapps go.</li>
  -</ul>
  -
  -</section>
  -
  -
  -<section name="Configuring Tomcat">
  -
  -<p>This section will acquaint you with the basic information used during
  -the configuration of the container.</p>
  -
  -<p>All of the information in the configuration files is read at startup,
  -meaning that any change to the files necessitates a restart of the container.
  -</p>
  -
  -</section>
  -
  -
  -<section name="Where to Go for Help">
  -
  -<p>While we've done our best to ensure that these documents are clearly
  -written and easy to understand, we may have missed something.  Provided
  -below are various web sites and mailing lists in case you get stuck.</p>
  -
  -<p>As Tomcat 4 is a new release of Tomcat, keep in mind that some of the
  -issues and solutions vary between the major versions of Tomcat (3.x versus
  -4.x).  As you search around the web, there will be some documentation that
  -is not relevant to Tomcat 4, but 3.x.  Doing 3.x things to 4.0 will probably
  -not work in most cases as the server.xml files are very different.</p>
  -
  -<ul>
  -<li>Current document - most documents will list potential hangups. Be sure
  -    to fully read the relevant documentation as it will save you much time
  -    and effort. There's nothing like scouring the web only to find out that
  -    the answer was right in front of you all along!</li>
  -<li>Jakarta <a href="http://jakarta.apache.org:8080/jyve-faq/Turbine/screen/MainMenu/action/SetAll/screen/DisplayTopics/faq_id/12/project_id/2;jsessionid=36lqy9k9x1">FAQ-o-matic</a>
  -    - a repository of FAQs for the various Jakarta subprojects, including
  -    Tomcat of course.</li>
  -<li>Tomcat FAQ at <a href="http://www.jguru.com/faq/home.jsp?topic=Tomcat">jGuru</a></li>
  -<li>Tomcat mailing list archives - numerous sites archive the Tomcat mailing
  -    lists. Since the links change over time, clicking here will search
  -    <a href="http://www.google.com/search?q=tomcat+mailing+list+archives">Google</a>.
  -    </li>
  -<li>The TOMCAT-USER mailing list, which you can subscribe to
  -    <a href="http://jakarta.apache.org/site/mail.html">here</a>. If you don't
  -    get a reply, then there's a good chance that your question was probably
  -    answered in the list archives or one of the FAQs.  Although questions
  -    about web application development in general are sometimes asked and
  -    answered, please focus your questions on Tomcat-specific issues.</li>
  -<li>The TOMCAT-DEV mailing list, which you can subscribe to
  -    <a href="http://jakarta.apache.org/site/mail.html">here</a>.  This list is
  -    <strong>reserved</strong> for discussions about the development of Tomcat
  -    itself.  Questions about Tomcat configuration, and the problems you run
  -    into while developing and running applications, will normally be more
  -    appropriate on the TOMCAT-USER list instead.</li>
  -</ul>
  -
  -<p>And, if you think something should be in the docs, by all means let us know
  -on the TOMCAT-DEV list, or send one of the doc authors email.</p>
  -
  -</section>
  -
  -</body>
  -
  -</document>
  +<?xml version="1.0"?>
  +<!DOCTYPE document [
  +  <!ENTITY project SYSTEM "project.xml">
  +]>
  +<document>
  +
  +    &project;
  +
  +    <properties>
  +        <author email="rslifka@sfu.ca">Robert Slifka</author>
  +        <title>Introduction</title>
  +    </properties>
  +
  +<body>
  +
  +
  +<section name="Introduction">
  +
  +<p>For administrators and web developers alike, there are some important bits
  +of information you should familiarize yourself with before starting out. This
  +document serves as a brief introduction to some of the concepts and
  +terminology behind the Tomcat container. As well, where to go when you need
  +help.</p>
  +
  +</section>
  +
  +
  +<section name="Terminology">
  +
  +<p>In the course of reading these documents, you'll run across a number of
  +terms; some specific to Tomcat, and others defined by the
  +<a href="http://java.sun.com/products/servlet/">Servlet</a> or
  +<a href="http://java.sun.com/products/jsp/">JSP</a> specifications.</p>
  +
  +<ul>
  +<li><strong>Context</strong> - In a nutshell, a Context is a
  +    web application.</li>
  +<li><strong>Term2</strong> - This is it.</li>
  +<li><strong>Term3</strong> - This is it!</li>
  +</ul>
  +
  +</section>
  +
  +
  +<section name="Directories and Files">
  +
  +<p>Throughout the docs, you'll notice there are numerous references to
  +<strong>$CATALINA_HOME</strong>. This represents the root of your Tomcat
  +installation. When we say, "This information can be found in your
  +$CATALINA_HOME/README.txt file" we mean to look at the README.txt file at the
  +root of your Tomcat install.</p>
  +
  +<p>For the complete description of the Tomcat distribution, each folder can be
  +found in the <a href="README.txt">README.txt</a> file, residing in the root
  +directory of your Tomcat installation. Here, we will cover the ones where
  +you'll be spending the majority of your time.</p>
  +
  +<ul>
  +<li><strong>/bin</strong> - Startup, shutdown, and other scripts. The
  +    <code>*.sh</code> files (for Unix systems) are functional duplicates of
  +    the <code>*.bat</code> files (for Windows systems).  Since the Win32
  +    command-line lacks certain functionality, there are some additional
  +    files in here.</li>
  +<li><strong>/conf</strong> - Configuration files and related DTDs.  The most
  +    important file in here is server.xml.  It is the main configuration file
  +    for the container.</li>
  +<li><strong>/logs</strong> - Log files are here by default.</li>
  +<li><strong>/webapps</strong> - This is where your webapps go.</li>
  +</ul>
  +
  +</section>
  +
  +
  +<section name="Configuring Tomcat">
  +
  +<p>This section will acquaint you with the basic information used during
  +the configuration of the container.</p>
  +
  +<p>All of the information in the configuration files is read at startup,
  +meaning that any change to the files necessitates a restart of the container.
  +</p>
  +
  +</section>
  +
  +
  +<section name="Where to Go for Help">
  +
  +<p>While we've done our best to ensure that these documents are clearly
  +written and easy to understand, we may have missed something.  Provided
  +below are various web sites and mailing lists in case you get stuck.</p>
  +
  +<p>As Tomcat 4 is a new release of Tomcat, keep in mind that some of the
  +issues and solutions vary between the major versions of Tomcat (3.x versus
  +4.x).  As you search around the web, there will be some documentation that
  +is not relevant to Tomcat 4, but 3.x.  Doing 3.x things to 4.0 will probably
  +not work in most cases as the server.xml files are very different.</p>
  +
  +<ul>
  +<li>Current document - most documents will list potential hangups. Be sure
  +    to fully read the relevant documentation as it will save you much time
  +    and effort. There's nothing like scouring the web only to find out that
  +    the answer was right in front of you all along!</li>
  +<li>Jakarta <a href="http://jakarta.apache.org:8080/jyve-faq/Turbine/screen/MainMenu/action/SetAll/screen/DisplayTopics/faq_id/12/project_id/2;jsessionid=36lqy9k9x1">FAQ-o-matic</a>
  +    - a repository of FAQs for the various Jakarta subprojects, including
  +    Tomcat of course.</li>
  +<li>Tomcat FAQ at <a href="http://www.jguru.com/faq/home.jsp?topic=Tomcat">jGuru</a></li>
  +<li>Tomcat mailing list archives - numerous sites archive the Tomcat mailing
  +    lists. Since the links change over time, clicking here will search
  +    <a href="http://www.google.com/search?q=tomcat+mailing+list+archives">Google</a>.
  +    </li>
  +<li>The TOMCAT-USER mailing list, which you can subscribe to
  +    <a href="http://jakarta.apache.org/site/mail.html">here</a>. If you don't
  +    get a reply, then there's a good chance that your question was probably
  +    answered in the list archives or one of the FAQs.  Although questions
  +    about web application development in general are sometimes asked and
  +    answered, please focus your questions on Tomcat-specific issues.</li>
  +<li>The TOMCAT-DEV mailing list, which you can subscribe to
  +    <a href="http://jakarta.apache.org/site/mail.html">here</a>.  This list is
  +    <strong>reserved</strong> for discussions about the development of Tomcat
  +    itself.  Questions about Tomcat configuration, and the problems you run
  +    into while developing and running applications, will normally be more
  +    appropriate on the TOMCAT-USER list instead.</li>
  +</ul>
  +
  +<p>And, if you think something should be in the docs, by all means let us know
  +on the TOMCAT-DEV list, or send one of the doc authors email.</p>
  +
  +</section>
  +
  +</body>
  +
  +</document>
  
  
  
  1.8       +754 -754  jakarta-tomcat-4.0/webapps/tomcat-docs/jndi-resources-howto.xml
  
  Index: jndi-resources-howto.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/jndi-resources-howto.xml,v
  retrieving revision 1.7
  retrieving revision 1.8
  diff -u -r1.7 -r1.8
  --- jndi-resources-howto.xml	2001/10/10 18:11:39	1.7
  +++ jndi-resources-howto.xml	2001/11/12 21:03:49	1.8
  @@ -1,754 +1,754 @@
  -<?xml version="1.0"?>
  -<!DOCTYPE document [
  -  <!ENTITY project SYSTEM "project.xml">
  -]>
  -<document>
  -
  -    &project;
  -
  -    <properties>
  -        <author email="craigmcc@apache.org">Craig R. McClanahan</author>
  -        <title>JNDI Resources HOW-TO</title>
  -    </properties>
  -
  -<body>
  -
  -
  -<section name="Introduction">
  -
  -<p>Tomcat 4 provides a JNDI <strong>InitialContext</strong> implementation
  -instance to web applications running under it, in a manner that is compatible
  -with those provided by a <a href="http://java.sun.com/j2ee">Java2 Enterprise
  -Edition</a> application server.  Entries in this <code>InitialContext</code>
  -are configured in the <code>$CATALINA_HOME/conf/server.xml</code> file, and
  -may be referenced by the following elements in the web application deployment
  -descriptor (<code>/WEB-INF/web.xml</code>) of your web application:</p>
  -<ul>
  -<li><code><strong>&lt;env-entry&gt;</strong></code> - Environment entry, a
  -    single-value parameter that can be used to configure how the application
  -    will operate.</li>
  -<li><code><strong>&lt;resource-ref&gt;</strong></code> - Resource reference,
  -    which is typically to an object factory for resources such as a JDBC
  -    <code>DataSource</code>, a JavaMail <code>Session</code>, or custom
  -    object factories configured into Tomcat 4.</li>
  -<li><code><strong>&lt;resource-env-ref&gt;</strong></code> - Resource
  -    environment reference, a new variation of <code>resource-ref</code>
  -    added in Servlet 2.3 that is simpler to configure for resources
  -    that do not require authentication information.</li>
  -</ul>
  -
  -<p>The <code>InitialContext</code> is configured as a web application is
  -initially deployed, and is made available to web application components (for
  -read-only access).  All configured entries and resources will be placed in
  -the <code>java:comp/env</code> portion of the JNDI namespace, so a typical
  -access to a resource - in this case, to a JDBC <code>DataSource</code> -
  -would look something like this:</p>
  -<source>
  -// Obtain our environment naming context
  -Context initCtx = new InitialContext();
  -Context envCtx = (Context) initCtx.lookup("java:comp/env");
  -
  -// Look up our data source
  -DataSource ds = (DataSource)
  -  envCtx.lookup("jdbc/EmployeeDB");
  -
  -// Allocate and use a connection from the pool
  -Connection conn = ds.getConnection();
  -... use this connection to access the database ...
  -conn.close();
  -</source>
  -
  -<p>See the following Specifications for more information about programming APIs
  -for JNDI, and for the features supported by Java2 Enterprise Edition (J2EE)
  -servers, which Tomcat emulates for the services that it provides:</p>
  -<ul>
  -<li><a href="http://java.sun.com/products/jndi/#download">Java Naming and
  -    Directory Interface</a> (included in JDK 1.4, available separately for
  -    prior JDK versions)</li>
  -<li><a href="http://java.sun.com/j2ee/download.html">J2EE Platform
  -    Specification</a> (in particular, see Chapter 5 on <em>Naming</em>)</li>
  -</ul>
  -
  -</section>
  -
  -
  -<section name="Configuring JNDI Resources">
  -
  -<p>Each available JNDI Resource is configured based on inclusion of the
  -following elements in the <code>$CATALINA_HOME/conf/server.xml</code>
  -file:</p>
  -<ul>
  -<li><a href="config/context.html#Environment Entries">&lt;Environment&gt;</a> -
  -    Configure names and values for scalar environment entries that will be
  -    exposed to the web application through the JNDI
  -    <code>InitialContext</code> (equivalent to the inclusion of an
  -    <code>&lt;env-entry&gt;</code> element in the web application
  -    deployment descriptor).</li>
  -<li><a href="config/context.html#Resource Definitions">&lt;Resource&gt;</a> -
  -    Configure the name and data type of a resource made available to the
  -    application (equivalent to the inclusion of a
  -    <code>&lt;resource-ref&gt;</code> element in the web application
  -    deployment descriptor).</li>
  -<li><a href="config/context.html#Resource Parameters">&lt;ResourceParams&gt;</a> -
  -    Configure the Java class name of the resource factory implementation to be
  -    used, as well as JavaBeans properties used to configure that resource
  -    factory.</li>
  -</ul>
  -
  -<p>Any number of these elements may be nested inside a
  -<a href="config/context.html">&lt;Context&gt;</a> element (to be associated
  -only with that particular web application) or inside a
  -<a href="config/defaultcontext.html">&lt;DefaultContext&gt;</a> element
  -(used to set the default configuration characteristics for automatically
  -deloyed applications).</p>
  -
  -<p>In addition, the names and values of all <code>&lt;env-entry&gt;</code>
  -elements included in the web application deployment descriptor
  -(<code>/WEB-INF/web.xml</code>) are configured into the initial context as
  -well, overriding corresponding values from <code>conf/server.xml</code>
  -<strong>only</strong> if allowed by the corresponding
  -<code>&lt;Environment&gt;</code> element (by setting the
  -<code>override</code> attribute to "true").</p>
  -
  -</section>
  -
  -
  -<section name="Tomcat Standard Resource Factories">
  -
  -  <p>Tomcat 4 includes a series of standard resource factories that can
  -  provide services to your web applications, but give you configuration
  -  flexibility (in <code>$CATALINA_HOME/conf/server.xml</code>) without
  -  modifying the web application or the deployment descriptor.  Each
  -  subsection below details the configuration and usage of the standard
  -  resource factories.</p>
  -
  -  <p>See <a href="#Adding Custom Resource Factories">Adding Custom
  -  Resource Factories</a> for information about how to create, install,
  -  configure, and use your own custom resource factory classes with
  -  Tomcat 4.</p>
  -
  -  <p><em>NOTE</em> - Of the standard resource factories, only the
  -  "JDBC Data Source" and "User Transaction" factories are mandated to
  -  be available on other platforms, and then they are required only if
  -  the platform implements the Java2 Enterprise Edition (J2EE) specs.
  -  All other standard resource factories, plus custom resource factories
  -  that you write yourself, are specific to Tomcat and cannot be assumed
  -  to be available on other containers.</p>
  -
  -  <subsection name="Generic JavaBean Resources">
  -
  -    <h3>0.  Introduction</h3>
  -
  -    <p>This resource factory can be used to create objects of <em>any</em>
  -    Java class that conforms to standard JavaBeans naming conventions (i.e.
  -    it has a zero-arguments constructor, and has property setters that
  -    conform to the setFoo() naming pattern.  The resource factory will
  -    create a new instance of the appropriate bean class every time a
  -    <code>lookup()</code> for this entry is made.</p>
  -
  -    <p>The steps required to use this facility are described below.</p>
  -
  -    <h3>1.  Create Your JavaBean Class</h3>
  -
  -    <p>Create the JavaBean class which will be instantiated each time
  -    that the resource factory is looked up.  For this example, assume
  -    you create a class <code>com.mycompany.MyBean</code>, which looks
  -    like this:</p>
  -
  -<source>
  -package com.mycompany;
  -
  -public class MyBean {
  -
  -  private String foo = "Default Foo";
  -
  -  public String getFoo() {
  -    return (this.foo);
  -  }
  -
  -  public void setFoo(String foo) {
  -    this.foo = foo;
  -  }
  -
  -  private int bar = 0;
  -
  -  public int getBar() {
  -    return (this.bar);
  -  }
  -
  -  public void setBar(int bar) {
  -    this.bar = bar;
  -  }
  -
  -
  -}
  -</source>
  -
  -  <h3>2.  Declare Your Resource Requirements</h3>
  -
  -  <p>Next, modify your web application deployment descriptor
  -  (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under which
  -  you will request new instances of this bean.  The simplest approach is
  -  to use a <code>&lt;resource-env-ref&gt;</code> element, like this:</p>
  -
  -<source>
  -&lt;resource-env-ref&gt;
  -  &lt;Description&gt;
  -    Object factory for MyBean instances.
  -  &lt;/Description&gt;
  -  &lt;resource-env-ref-name&gt;
  -    bean/MyBeanFactory
  -  &lt;/resource-env-ref-name&gt;
  -  &lt;resource-env-ref-type&gt;
  -    com.mycompany.MyBean
  -  &lt;/resource-env-ref-type&gt;
  -&lt;resource-env-ref&gt;
  -</source>
  -
  -    <p><strong>WARNING</strong> - Be sure you respect the element ordering
  -    that is required by the DTD for web application deployment descriptors!
  -    See the
  -    <a href="http://java.sun.com/products/servlet/download.html">Servlet
  -    Specification</a> for details.</p>
  -
  -  <h3>3.  Code Your Application's Use Of This Resource</h3>
  -
  -  <p>A typical use of this resource environment reference might look
  -  like this:</p>
  -
  -<source>
  -Context initCtx = new InitialContext();
  -Context envCtx = (Context) initCtx.lookup("java:comp/env");
  -MyBean bean = (MyBean) envCtx.lookup("bean/MyBeanFactory");
  -
  -writer.println("foo = " + bean.getFoo() + ", bar = " +
  -               bean.getBar());
  -</source>
  -
  -    <h3>4.  Configure Tomcat's Resource Factory</h3>
  -
  -    <p>To configure Tomcat's resource factory, add an elements like this to the
  -    <code>$CATALINA_HOME/conf/server.xml</code> file, nested inside the
  -    <code>Context</code> element for this web application (or nested inside
  -    a <code>DefaultContext</code> element for the surrounding
  -    <code>&lt;Host&gt;</code> or <code>&lt;Engine&gt;</code> element.</p>
  -<source>
  -&lt;Context ...&gt;
  -  ...
  -  &lt;Resource name="bean/MyBeanFactory" auth="Container"
  -            type="com.mycompany.MyBean"/&gt;
  -  &lt;ResourceParams name="bean/MyBeanFactory"&gt;
  -    &lt;parameter&gt;
  -      &lt;name&gt;factory&lt;/name&gt;
  -      &lt;value&gt;org.apache.naming.factory.BeanFactory&lt;/value&gt;
  -    &lt;/parameter&gt;
  -    &lt;parameter&gt;
  -      &lt;name&gt;bar&lt;/name&gt;
  -      &lt;value&gt;23&lt;/value&gt;
  -    &lt;/parameter&gt;
  -  &lt;/ResourceParams&gt;
  -  ...
  -&lt;/Context&gt;
  -</source>
  -
  -    <p>Note that the resource name (here, <code>bean/MyBeanFactory</code>
  -    must match the value specified in the web application deployment
  -    descriptor.  We are also initializing the value of the <code>bar</code>
  -    property, which will cause <code>setBar(23)</code> to be called before
  -    the new bean is returned.  Because we are not initializing the
  -    <code>foo</code> property (although we could have), the bean will
  -    contain whatever default value is set up by its constructor.</p>
  -
  -  </subsection>
  -
  -
  -  <subsection name="JavaMail Sessions">
  -
  -    <h3>0.  Introduction</h3>
  -
  -    <p>In many web applications, sending electronic mail messages is a
  -    required part of the system's functionality.  The
  -    <a href="http://java.sun.com/products/javamail">Java Mail</a> API
  -    makes this process relatively straightforward, but requires many
  -    configuration details that the client application must be aware of
  -    (including the name of the SMTP host to be used for message sending).</p>
  -
  -    <p>Tomcat 4 includes a standard resource factory that will create
  -    <code>javax.mail.Session</code> session instances for you, already
  -    connected to the SMTP server that is configured in <code>server.xml</code>.
  -    In this way, the application is totally insulated from changes in the
  -    email server configuration environment - it simply asks for, and receives,
  -    a preconfigured session whenever needed.</p>
  -
  -    <p>The steps required for this are outlined below.</p>
  -
  -    <h3>1.  Declare Your Resource Requirements</h3>
  -
  -    <p>The first thing you should do is modify the web application deployment
  -    descriptor (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under
  -    which you will look up preconfigured sessions.  By convention, all such
  -    names should resolve to the <code>mail</code> subcontext (relative to the
  -    standard <code>java:comp/env</code> naming context that is the root of
  -    all provided resource factories.  A typical <code>web.xml</code> entry
  -    might look like this:</p>
  -<source>
  -&lt;resource-ref&gt;
  -  &lt;description&gt;
  -    Resource reference to a factory for javax.mail.Session
  -    instances that may be used for sending electronic mail
  -    messages, preconfigured to connect to the appropriate
  -    SMTP server.
  -  &lt;/description&gt;
  -  &lt;res-ref-name&gt;
  -    mail/Session
  -  &lt;/res-ref-name&gt;
  -  &lt;res-type&gt;
  -    javax.mail.Session
  -  &lt;/res-type&gt;
  -  &lt;res-auth&gt;
  -    Container
  -  &lt;/res-auth&gt;
  -&lt;/resource-ref&gt;
  -</source>
  -
  -    <p><strong>WARNING</strong> - Be sure you respect the element ordering
  -    that is required by the DTD for web application deployment descriptors!
  -    See the
  -    <a href="http://java.sun.com/products/servlet/download.html">Servlet
  -    Specification</a> for details.</p>
  -
  -    <h3>2.  Code Your Application's Use Of This Resource</h3>
  -
  -    <p>A typical use of this resource reference might look like this:</p>
  -<source>
  -Context initCtx = new InitialContext();
  -Context envCtx = (Context) initCtx.lookup("java:comp/env");
  -Session session = (Session) envCtx.lookup("mail/Session");
  -
  -Message message = new MimeMessage(session);
  -message.setFrom(new InternetAddress(request.getParameter("from"));
  -InternetAddress to[] = new InternetAddress[1];
  -to[0] = new InternetAddress(request.getParameter("to"));
  -message.setRecipients(Message.RecipientType.TO, to);
  -message.setSubject(request.getParameter("subject"));
  -message.setContent(request.getParameter("content"), "text/plain");
  -Transport.send(message);
  -</source>
  -
  -    <p>Note that the application uses the same resource reference name
  -    that was declared in the web application deployment descriptor.  This
  -    is matched up against the resource factory that is configured in
  -    <code>$CATALINA_HOME/conf/server.xml</code>, as described below.</p>
  -
  -    <h3>3.  Configure Tomcat's Resource Factory</h3>
  -
  -    <p>To configure Tomcat's resource factory, add an elements like this to the
  -    <code>$CATALINA_HOME/conf/server.xml</code> file, nested inside the
  -    <code>Context</code> element for this web application (or nested inside
  -    a <code>DefaultContext</code> element for the surrounding
  -    <code>&lt;Host&gt;</code> or <code>&lt;Engine&gt;</code> element.</p>
  -<source>
  -&lt;Context ...&gt;
  -  ...
  -  &lt;Resource name="mail/Session" auth="Container"
  -            type="javax.mail.Session"/&gt;
  -  &lt;ResourceParams name="mail/Session"&gt;
  -    &lt;parameter&gt;
  -      &lt;name&gt;mail.smtp.host&lt;/name&gt;
  -      &lt;value&gt;localhost&lt;/value&gt;
  -    &lt;/parameter&gt;
  -  &lt;/ResourceParams&gt;
  -  ...
  -&lt;/Context&gt;
  -</source>
  -
  -    <p>Note that the resource name (here, <code>mail/Session</code>) must
  -    match the value specified in the web application deployment descriptor.
  -    Customize the value of the <code>mail.smtp.host</code> parameter to
  -    point at the server that provides SMTP service for your network.</p>
  -
  -    <h3>Example Application</h3>
  -
  -    <p>The <code>/examples</code> application included with Tomcat contains
  -    an example of utilizing this resource factory.  It is accessed via the
  -    "JSP Examples" link.  The source code for the servlet that actually
  -    sends the mail message is in
  -    <code>/WEB-INF/classes/SendMailServlet.java</code>.</p>
  -
  -    <p><strong>WARNING</strong> - The default configuration assumes that
  -    there is an SMTP server listing on port 25 on <code>localhost</code>.
  -    If this is not the case, edit the
  -    <code>$CATALINA_HOME/conf/server.xml</code> file, and modify the
  -    parameter value for the <code>mail.smtp.host</code> parameter to be
  -    the host name of an SMTP server on your network.</p>
  -
  -  </subsection>
  -
  -  <subsection name="JDBC Data Sources">
  -
  -    <h3>0.  Introduction</h3>
  -
  -    <p>Many web applications need to access a database via a JDBC driver,
  -    to support the functionality required by that application.  The J2EE
  -    Platform Specification requires J2EE Application Servers to make
  -    available a <em>DataSource</em> implementation (that is, a connection
  -    pool for JDBC connections) for this purpose.  Tomcat 4 offers exactly
  -    the same support, so that database-based applications you develop on
  -    Tomcat using this service will run unchanged on any J2EE server.</p>
  -
  -    <p>For information about JDBC, you should consult the following:</p>
  -    <ul>
  -    <li><a href="http://java.sun.com/products/jdbc/">http://java.sun.com/products/jdbc/</a> -
  -        Home page for information about Java Database Connectivity.</li>
  -    <li><a href="http://java.sun.com/j2se/1.3/docs/guide/jdbc/spec2/jdbc2.1.frame.html">http://java.sun.com/j2se/1.3/docs/guide/jdbc/spec2/jdbc2.1.frame.html</a> -
  -        The JDBC 2.1 API Specification.</li>
  -    <li><a href="http://java.sun.com/products/jdbc/jdbc20.stdext.pdf">http://java.sun.com/products/jdbc/jdbc20.stdext.pdf</a> -
  -        The JDBC 2.0 Standard Extension API (including the
  -        <code>javax.sql.DataSource</code> API).  This package is now known
  -        as the "JDBC Optional Package".</li>
  -    <li><a href="http://java.sun.com/j2ee/download.html">http://java.sun.com/j2ee/download.html</a> -
  -        The J2EE Platform Specification (covers the JDBC facilities that
  -        all J2EE platforms must provide to applications).</li>
  -    </ul>
  -
  -    <p><strong>NOTE</strong> - The default data source support in Tomcat
  -    supports Tyrex.  However, it is possible to use any other connection pool
  -    that implements <code>javax.sql.DataSource</code>, by writing your own
  -    custom resource factory, as described
  -    <a href="#Adding Custom Resource Factories">below</a>.</p>
  -
  -    <h3>1.  Install Your JDBC Driver</h3>
  -
  -    <p>Use of the <em>JDBC Data Sources</em> JNDI Resource Factory requires
  -    that you make an appropriate JDBC driver available to both Tomcat internal
  -    classes and to your web application.  This is most easily accomplished by
  -    installing the driver's JAR file(s) into the
  -    <code>$CATALINA_HOME/common/lib</code> directory, which makes the driver
  -    available both to the resource factory and to your application.</p>
  -
  -    <h3>2.  Declare Your Resource Requirements</h3>
  -
  -    <p>Next, modify the web application deployment descriptor
  -    (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under
  -    which you will look up preconfigured data source.  By convention, all such
  -    names should resolve to the <code>jdbc</code> subcontext (relative to the
  -    standard <code>java:comp/env</code> naming context that is the root of
  -    all provided resource factories.  A typical <code>web.xml</code> entry
  -    might look like this:</p>
  -<source>
  -&lt;resource-ref&gt;
  -  &lt;description&gt;
  -    Resource reference to a factory for java.sql.Connection
  -    instances that may be used for talking to a particular
  -    database that is configured in the server.xml file.
  -  &lt;/description&gt;
  -  &lt;res-ref-name&gt;
  -    jdbc/EmployeDB
  -  &lt;/res-ref-name&gt;
  -  &lt;res-type&gt;
  -    javax.sql.DataSource
  -  &lt;/res-type&gt;
  -  &lt;res-auth&gt;
  -    Container
  -  &lt;/res-auth&gt;
  -&lt;/resource-ref&gt;
  -</source>
  -
  -    <p><strong>WARNING</strong> - Be sure you respect the element ordering
  -    that is required by the DTD for web application deployment descriptors!
  -    See the
  -    <a href="http://java.sun.com/products/servlet/download.html">Servlet
  -    Specification</a> for details.</p>
  -
  -    <h3>3.  Code Your Application's Use Of This Resource</h3>
  -
  -    <p>A typical use of this resource reference might look like this:</p>
  -<source>
  -Context initCtx = new InitialContext();
  -Context envCtx = (Context) initCtx.lookup("java:comp/env");
  -DataSource ds = (DataSource)
  -  envCtx.lookup("jdbc/EmployeeDB");
  -
  -Connection conn = ds.getConnection();
  -... use this connection to access the database ...
  -conn.close();
  -</source>
  -
  -    <p>Note that the application uses the same resource reference name
  -    that was declared in the web application deployment descriptor.  This
  -    is matched up against the resource factory that is configured in
  -    <code>$CATALINA_HOME/conf/server.xml</code>, as described below.</p>
  -
  -    <h3>4.  Configure Tomcat's Resource Factory</h3>
  -
  -    <p>To configure Tomcat's resource factory, add an elements like this to the
  -    <code>$CATALINA_HOME/conf/server.xml</code> file, nested inside the
  -    <code>Context</code> element for this web application (or nested inside
  -    a <code>DefaultContext</code> element for the surrounding
  -    <code>&lt;Host&gt;</code> or <code>&lt;Engine&gt;</code> element.</p>
  -<source>
  -&lt;Context ...&gt;
  -  ...
  -  &lt;Resource name="jdbc/EmployeeDB" auth="Container"
  -            type="javax.sql.DataSource"/&gt;
  -  &lt;ResourceParams name="jdbc/EmployeeDB"&gt;
  -    &lt;parameter&gt;
  -      &lt;name&gt;user&lt;/name&gt;
  -      &lt;value&gt;dbusername&lt;/value&gt;
  -    &lt;/parameter&gt;
  -    &lt;parameter&gt;
  -      &lt;name&gt;password&lt;/name&gt;
  -      &lt;value&gt;dbpassword&lt;/value&gt;
  -    &lt;/parameter&gt;
  -    &lt;parameter&gt;
  -      &lt;name&gt;driverClassName&lt;/name&gt;
  -      &lt;value&gt;org.hsql.jdbcDriver&lt;/value&gt;
  -    &lt;/parameter&gt;
  -    &lt;parameter&gt;
  -      &lt;name&gt;driverName&lt;/name&gt;
  -      &lt;value&gt;jdbc:HypersonicSQL:database&lt;/value&gt;
  -    &lt;/parameter&gt;
  -  &lt;/ResourceParams&gt;
  -  ...
  -&lt;/Context&gt;
  -</source>
  -
  -    <p>Note that the resource name (here, <code>jdbc/EmployeeDB</code>) must
  -    match the value specified in the web application deployment descriptor.
  -    Customize the value of the <code>mail.smtp.host</code> parameter to
  -    point at the server that provides SMTP service for your network.</p>
  -
  -    <p>This example assumes that you are using the HypersonicSQL database
  -    JDBC driver.  Customize the <code>driverClassName</code> and
  -    <code>driverName</code> parameters to match your actual database's
  -    JDBC driver and connection URL.</p>
  -
  -  </subsection>
  -
  -  <subsection name="User Transactions">
  -
  -    <p>If you utilize Tyrex for your JDBC resource factory as described
  -    <a href="#JDBC Data Sources">above</a>, you will also have support for
  -    the <code>java.transaction.UserTransaction</code> resource provided by
  -    Tyrex (since it is XA-capable).  To use this feature, code your
  -    application as follows:</p>
  -<source>
  -Context initCtx = new InitialContext();
  -Context envCtx = (Context) initCtx.lookup("java:comp/env");
  -Transaction tx = (Transaction) envCtx.lookup("UserTransaction");
  -
  -tx.begin();
  -... perform transactional operations on data ...
  -tx.commit();
  -</source>
  -
  -    <p>This is useful when you need to do "two-phased commits" across more
  -    than one database, where the commit needs to either succeed completely
  -    or fail completely across all associated databases.  This feature
  -    requires a JDBC driver that also supports XA capabilities.  See the
  -    J2EE and JDBC documentation for more information.</p>
  -
  -  </subsection>
  -
  -</section>
  -
  -
  -<section name="Adding Custom Resource Factories">
  -
  -  <p>If none of the standard resource factories meet your needs, you can
  -  write your own factory and integrate it into Tomcat 4, and then configure
  -  the use of this factory in the <code>conf/server.xml</code> configuration
  -  file.  In the example below, we will create a factory that only knows how
  -  to create <code>com.mycompany.MyBean</code> beans, from the
  -  <a href="Generic JavaBean Resources">Generic JavaBean Resources</a>
  -  example, above.</p>
  -
  -  <h3>1.  Write A Resource Factory Class</h3>
  -
  -  <p>You must write a class that implements the JNDI service provider
  -  <code>javax.naming.spi.ObjectFactory</code> inteface.  Every time your
  -  web application calls <code>lookup()</code> on a context entry that is
  -  bound to this factory, the <code>getObjectInstance()</code> method is
  -  called, with the following arguments:</p>
  -  <ul>
  -  <li><strong>Object obj</strong> - The (possibly null) object containing
  -      location or reference information that can be used in creating an
  -      object.  For Tomcat, this will always be an object of type
  -      <code>javax.naming.Reference</code>, which contains the class name
  -      of this factory class, as well as the configuration properties
  -      (from <code>conf/server.xml</code>) to use in creating objects
  -      to be returned.</li>
  -  <li><strong>Name name</strong> - The name to which this factory is bound
  -      relative to <code>nameCtx</code>, or <code>null</code> if no name
  -      is specified.</li>
  -  <li><strong>Context nameCtx</strong> - The context relative to which the
  -      <code>name</code> parameter is specified, or <code>null</code> if
  -      <code>name</code> is relative to the default initial context.</li>
  -  <li><strong>Hashtable environment</strong> - The (possibly null)
  -      environment that is used in creating this object.  This is generally
  -      ignored in Tomcat object factories.</li>
  -  </ul>
  -
  -  <p>To create a resource factory that knows how to produce <code>MyBean</code>
  -  instances, you might create a class like this:</p>
  -
  -<source>
  -package com.mycompany;
  -
  -import java.util.Enumeration;
  -import java.util.Hashtable;
  -import javax.naming.Context;
  -import javax.naming.Name;
  -import javax.naming.NamingException;
  -import javax.naming.RefAddr;
  -import javax.naming.Reference;
  -import javax.naming.spi.ObjectFactory;
  -
  -public class MyBeanFactory implements ObjectFactory {
  -
  -  public Object getObjectInstance(Object obj,
  -      Name name, Context nameCtx, Hashtable environment)
  -      throws NamingException {
  -
  -      // Acquire an instance of our specified bean class
  -      MyBean bean = new MyBean();
  -
  -      // Customize the bean properties from our attributes
  -      Reference ref = (Reference) obj;
  -      Enumeration addrs = ref.getAll();
  -      while (addrs.hasMoreElements()) {
  -          RefAddr addr = (RefAddr) addrs.nextElement();
  -          String name = addr.getType();
  -          String value = (String) addr.getContent();
  -          if (name.equals("foo")) {
  -              bean.setFoo(value);
  -          } else if (name.equals("bar")) {
  -              try {
  -                  bean.setBar(Integer.parseInt(value));
  -              } catch (NumberFormatException e) {
  -                  throw new NamingException("Invalid 'bar' value " + value);
  -              }
  -          }
  -      }
  -
  -      // Return the customized instance
  -      return (bean);
  -
  -  }
  -
  -}
  -</source>
  -
  -  <p>In this example, we are unconditionally creating a new instance of
  -  the <code>com.mycompany.MyBean</code> class, and populating its properties
  -  based on the parameters included in the <code>&lt;ResourceParams&gt;</code>
  -  element that configures this factory (see below).  You should note that any
  -  parameter named <code>factory</code> should be skipped - that parameter is
  -  used to specify the name of the factory class itself (in this case,
  -  <code>com.mycompany.MyBeanFactory</code>) rather than a property of the
  -  bean being configured.</p>
  -
  -  <p>For more information about <code>ObjectFactory</code>, see the
  -  <a href="http://java.sun.com/products/jndi/docs.html">JNDI 1.2 Service
  -  Provider Interface (SPI) Specification</a>.</p>
  -
  -  <p>You will need to compile this class against a class path that includes
  -  all of the JAR files in the <code>$CATALINA_HOME/common/lib</code> and
  -  <code>$CATALINA_HOME/server/lib</code> directories.  When you are through,
  -  place the factory class (and the corresponding bean class) unpacked under
  -  <code>$CATALINA_HOME/common/classes</code>, or in a JAR file inside
  -  <code>$CATALINA_HOME/common/lib</code>.  In this way, the required class
  -  files are visible to both Catalina internal resources and your web
  -  application.</p>
  -
  -  <h3>2.  Declare Your Resource Requirements</h3>
  -
  -  <p>Next, modify your web application deployment descriptor
  -  (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under which
  -  you will request new instances of this bean.  The simplest approach is
  -  to use a <code>&lt;resource-env-ref&gt;</code> element, like this:</p>
  -
  -<source>
  -&lt;resource-env-ref&gt;
  -  &lt;description&gt;
  -    Object factory for MyBean instances.
  -  &lt;/description&gt;
  -  &lt;resource-env-ref-name&gt;
  -    bean/MyBeanFactory
  -  &lt;/resource-env-ref-name&gt;
  -  &lt;resource-env-ref-type&gt;
  -    com.mycompany.MyBean
  -  &lt;/resource-env-ref-type&gt;
  -&lt;resource-env-ref&gt;
  -</source>
  -
  -    <p><strong>WARNING</strong> - Be sure you respect the element ordering
  -    that is required by the DTD for web application deployment descriptors!
  -    See the
  -    <a href="http://java.sun.com/products/servlet/download.html">Servlet
  -    Specification</a> for details.</p>
  -
  -  <h3>3.  Code Your Application's Use Of This Resource</h3>
  -
  -  <p>A typical use of this resource environment reference might look
  -  like this:</p>
  -
  -<source>
  -Context initCtx = new InitialContext();
  -Context envCtx = (Context) initCtx.lookup("java:comp/env");
  -MyBean bean = (MyBean) envCtx.lookup("bean/MyBeanFactory");
  -
  -writer.println("foo = " + bean.getFoo() + ", bar = " +
  -               bean.getBar());
  -</source>
  -
  -    <h3>4.  Configure Tomcat's Resource Factory</h3>
  -
  -    <p>To configure Tomcat's resource factory, add an elements like this to the
  -    <code>$CATALINA_HOME/conf/server.xml</code> file, nested inside the
  -    <code>Context</code> element for this web application (or nested inside
  -    a <code>DefaultContext</code> element for the surrounding
  -    <code>&lt;Host&gt;</code> or <code>&lt;Engine&gt;</code> element.</p>
  -<source>
  -&lt;Context ...&gt;
  -  ...
  -  &lt;Resource name="bean/MyBeanFactory" auth="Container"
  -            type="com.mycompany.MyBean"/&gt;
  -  &lt;ResourceParams name="bean/MyBeanFactory"&gt;
  -    &lt;parameter&gt;
  -      &lt;name&gt;factory&lt;/name&gt;
  -      &lt;value&gt;com.mycompany.MyBeanFactory&lt;/value&gt;
  -    &lt;/parameter&gt;
  -    &lt;parameter&gt;
  -      &lt;name&gt;bar&lt;/name&gt;
  -      &lt;value&gt;23&lt;/value&gt;
  -    &lt;/parameter&gt;
  -  &lt;/ResourceParams&gt;
  -  ...
  -&lt;/Context&gt;
  -</source>
  -
  -    <p>Note that the resource name (here, <code>bean/MyBeanFactory</code>
  -    must match the value specified in the web application deployment
  -    descriptor.  We are also initializing the value of the <code>bar</code>
  -    property, which will cause <code>setBar(23)</code> to be called before
  -    the new bean is returned.  Because we are not initializing the
  -    <code>foo</code> property (although we could have), the bean will
  -    contain whatever default value is set up by its constructor.</p>
  -
  -    <p>You will also note that, from the application developer's perspective,
  -    the declaration of the resource environment reference, and the programming
  -    used to request new instances, is identical to the approach used for the
  -    <em>Generic JavaBean Resources</em> example.  This illustrates one of the
  -    advantages of using JNDI resources to encapsulate functionality - you can
  -    change the underlying implementation without necessarily having to
  -    modify applications using the resources, as long as you maintain
  -    compatible APIs.</p>
  -
  -</section>
  -
  -
  -
  -</body>
  -
  -</document>
  +<?xml version="1.0"?>
  +<!DOCTYPE document [
  +  <!ENTITY project SYSTEM "project.xml">
  +]>
  +<document>
  +
  +    &project;
  +
  +    <properties>
  +        <author email="craigmcc@apache.org">Craig R. McClanahan</author>
  +        <title>JNDI Resources HOW-TO</title>
  +    </properties>
  +
  +<body>
  +
  +
  +<section name="Introduction">
  +
  +<p>Tomcat 4 provides a JNDI <strong>InitialContext</strong> implementation
  +instance to web applications running under it, in a manner that is compatible
  +with those provided by a <a href="http://java.sun.com/j2ee">Java2 Enterprise
  +Edition</a> application server.  Entries in this <code>InitialContext</code>
  +are configured in the <code>$CATALINA_HOME/conf/server.xml</code> file, and
  +may be referenced by the following elements in the web application deployment
  +descriptor (<code>/WEB-INF/web.xml</code>) of your web application:</p>
  +<ul>
  +<li><code><strong>&lt;env-entry&gt;</strong></code> - Environment entry, a
  +    single-value parameter that can be used to configure how the application
  +    will operate.</li>
  +<li><code><strong>&lt;resource-ref&gt;</strong></code> - Resource reference,
  +    which is typically to an object factory for resources such as a JDBC
  +    <code>DataSource</code>, a JavaMail <code>Session</code>, or custom
  +    object factories configured into Tomcat 4.</li>
  +<li><code><strong>&lt;resource-env-ref&gt;</strong></code> - Resource
  +    environment reference, a new variation of <code>resource-ref</code>
  +    added in Servlet 2.3 that is simpler to configure for resources
  +    that do not require authentication information.</li>
  +</ul>
  +
  +<p>The <code>InitialContext</code> is configured as a web application is
  +initially deployed, and is made available to web application components (for
  +read-only access).  All configured entries and resources will be placed in
  +the <code>java:comp/env</code> portion of the JNDI namespace, so a typical
  +access to a resource - in this case, to a JDBC <code>DataSource</code> -
  +would look something like this:</p>
  +<source>
  +// Obtain our environment naming context
  +Context initCtx = new InitialContext();
  +Context envCtx = (Context) initCtx.lookup("java:comp/env");
  +
  +// Look up our data source
  +DataSource ds = (DataSource)
  +  envCtx.lookup("jdbc/EmployeeDB");
  +
  +// Allocate and use a connection from the pool
  +Connection conn = ds.getConnection();
  +... use this connection to access the database ...
  +conn.close();
  +</source>
  +
  +<p>See the following Specifications for more information about programming APIs
  +for JNDI, and for the features supported by Java2 Enterprise Edition (J2EE)
  +servers, which Tomcat emulates for the services that it provides:</p>
  +<ul>
  +<li><a href="http://java.sun.com/products/jndi/#download">Java Naming and
  +    Directory Interface</a> (included in JDK 1.4, available separately for
  +    prior JDK versions)</li>
  +<li><a href="http://java.sun.com/j2ee/download.html">J2EE Platform
  +    Specification</a> (in particular, see Chapter 5 on <em>Naming</em>)</li>
  +</ul>
  +
  +</section>
  +
  +
  +<section name="Configuring JNDI Resources">
  +
  +<p>Each available JNDI Resource is configured based on inclusion of the
  +following elements in the <code>$CATALINA_HOME/conf/server.xml</code>
  +file:</p>
  +<ul>
  +<li><a href="config/context.html#Environment Entries">&lt;Environment&gt;</a> -
  +    Configure names and values for scalar environment entries that will be
  +    exposed to the web application through the JNDI
  +    <code>InitialContext</code> (equivalent to the inclusion of an
  +    <code>&lt;env-entry&gt;</code> element in the web application
  +    deployment descriptor).</li>
  +<li><a href="config/context.html#Resource Definitions">&lt;Resource&gt;</a> -
  +    Configure the name and data type of a resource made available to the
  +    application (equivalent to the inclusion of a
  +    <code>&lt;resource-ref&gt;</code> element in the web application
  +    deployment descriptor).</li>
  +<li><a href="config/context.html#Resource Parameters">&lt;ResourceParams&gt;</a> -
  +    Configure the Java class name of the resource factory implementation to be
  +    used, as well as JavaBeans properties used to configure that resource
  +    factory.</li>
  +</ul>
  +
  +<p>Any number of these elements may be nested inside a
  +<a href="config/context.html">&lt;Context&gt;</a> element (to be associated
  +only with that particular web application) or inside a
  +<a href="config/defaultcontext.html">&lt;DefaultContext&gt;</a> element
  +(used to set the default configuration characteristics for automatically
  +deloyed applications).</p>
  +
  +<p>In addition, the names and values of all <code>&lt;env-entry&gt;</code>
  +elements included in the web application deployment descriptor
  +(<code>/WEB-INF/web.xml</code>) are configured into the initial context as
  +well, overriding corresponding values from <code>conf/server.xml</code>
  +<strong>only</strong> if allowed by the corresponding
  +<code>&lt;Environment&gt;</code> element (by setting the
  +<code>override</code> attribute to "true").</p>
  +
  +</section>
  +
  +
  +<section name="Tomcat Standard Resource Factories">
  +
  +  <p>Tomcat 4 includes a series of standard resource factories that can
  +  provide services to your web applications, but give you configuration
  +  flexibility (in <code>$CATALINA_HOME/conf/server.xml</code>) without
  +  modifying the web application or the deployment descriptor.  Each
  +  subsection below details the configuration and usage of the standard
  +  resource factories.</p>
  +
  +  <p>See <a href="#Adding Custom Resource Factories">Adding Custom
  +  Resource Factories</a> for information about how to create, install,
  +  configure, and use your own custom resource factory classes with
  +  Tomcat 4.</p>
  +
  +  <p><em>NOTE</em> - Of the standard resource factories, only the
  +  "JDBC Data Source" and "User Transaction" factories are mandated to
  +  be available on other platforms, and then they are required only if
  +  the platform implements the Java2 Enterprise Edition (J2EE) specs.
  +  All other standard resource factories, plus custom resource factories
  +  that you write yourself, are specific to Tomcat and cannot be assumed
  +  to be available on other containers.</p>
  +
  +  <subsection name="Generic JavaBean Resources">
  +
  +    <h3>0.  Introduction</h3>
  +
  +    <p>This resource factory can be used to create objects of <em>any</em>
  +    Java class that conforms to standard JavaBeans naming conventions (i.e.
  +    it has a zero-arguments constructor, and has property setters that
  +    conform to the setFoo() naming pattern.  The resource factory will
  +    create a new instance of the appropriate bean class every time a
  +    <code>lookup()</code> for this entry is made.</p>
  +
  +    <p>The steps required to use this facility are described below.</p>
  +
  +    <h3>1.  Create Your JavaBean Class</h3>
  +
  +    <p>Create the JavaBean class which will be instantiated each time
  +    that the resource factory is looked up.  For this example, assume
  +    you create a class <code>com.mycompany.MyBean</code>, which looks
  +    like this:</p>
  +
  +<source>
  +package com.mycompany;
  +
  +public class MyBean {
  +
  +  private String foo = "Default Foo";
  +
  +  public String getFoo() {
  +    return (this.foo);
  +  }
  +
  +  public void setFoo(String foo) {
  +    this.foo = foo;
  +  }
  +
  +  private int bar = 0;
  +
  +  public int getBar() {
  +    return (this.bar);
  +  }
  +
  +  public void setBar(int bar) {
  +    this.bar = bar;
  +  }
  +
  +
  +}
  +</source>
  +
  +  <h3>2.  Declare Your Resource Requirements</h3>
  +
  +  <p>Next, modify your web application deployment descriptor
  +  (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under which
  +  you will request new instances of this bean.  The simplest approach is
  +  to use a <code>&lt;resource-env-ref&gt;</code> element, like this:</p>
  +
  +<source>
  +&lt;resource-env-ref&gt;
  +  &lt;Description&gt;
  +    Object factory for MyBean instances.
  +  &lt;/Description&gt;
  +  &lt;resource-env-ref-name&gt;
  +    bean/MyBeanFactory
  +  &lt;/resource-env-ref-name&gt;
  +  &lt;resource-env-ref-type&gt;
  +    com.mycompany.MyBean
  +  &lt;/resource-env-ref-type&gt;
  +&lt;resource-env-ref&gt;
  +</source>
  +
  +    <p><strong>WARNING</strong> - Be sure you respect the element ordering
  +    that is required by the DTD for web application deployment descriptors!
  +    See the
  +    <a href="http://java.sun.com/products/servlet/download.html">Servlet
  +    Specification</a> for details.</p>
  +
  +  <h3>3.  Code Your Application's Use Of This Resource</h3>
  +
  +  <p>A typical use of this resource environment reference might look
  +  like this:</p>
  +
  +<source>
  +Context initCtx = new InitialContext();
  +Context envCtx = (Context) initCtx.lookup("java:comp/env");
  +MyBean bean = (MyBean) envCtx.lookup("bean/MyBeanFactory");
  +
  +writer.println("foo = " + bean.getFoo() + ", bar = " +
  +               bean.getBar());
  +</source>
  +
  +    <h3>4.  Configure Tomcat's Resource Factory</h3>
  +
  +    <p>To configure Tomcat's resource factory, add an elements like this to the
  +    <code>$CATALINA_HOME/conf/server.xml</code> file, nested inside the
  +    <code>Context</code> element for this web application (or nested inside
  +    a <code>DefaultContext</code> element for the surrounding
  +    <code>&lt;Host&gt;</code> or <code>&lt;Engine&gt;</code> element.</p>
  +<source>
  +&lt;Context ...&gt;
  +  ...
  +  &lt;Resource name="bean/MyBeanFactory" auth="Container"
  +            type="com.mycompany.MyBean"/&gt;
  +  &lt;ResourceParams name="bean/MyBeanFactory"&gt;
  +    &lt;parameter&gt;
  +      &lt;name&gt;factory&lt;/name&gt;
  +      &lt;value&gt;org.apache.naming.factory.BeanFactory&lt;/value&gt;
  +    &lt;/parameter&gt;
  +    &lt;parameter&gt;
  +      &lt;name&gt;bar&lt;/name&gt;
  +      &lt;value&gt;23&lt;/value&gt;
  +    &lt;/parameter&gt;
  +  &lt;/ResourceParams&gt;
  +  ...
  +&lt;/Context&gt;
  +</source>
  +
  +    <p>Note that the resource name (here, <code>bean/MyBeanFactory</code>
  +    must match the value specified in the web application deployment
  +    descriptor.  We are also initializing the value of the <code>bar</code>
  +    property, which will cause <code>setBar(23)</code> to be called before
  +    the new bean is returned.  Because we are not initializing the
  +    <code>foo</code> property (although we could have), the bean will
  +    contain whatever default value is set up by its constructor.</p>
  +
  +  </subsection>
  +
  +
  +  <subsection name="JavaMail Sessions">
  +
  +    <h3>0.  Introduction</h3>
  +
  +    <p>In many web applications, sending electronic mail messages is a
  +    required part of the system's functionality.  The
  +    <a href="http://java.sun.com/products/javamail">Java Mail</a> API
  +    makes this process relatively straightforward, but requires many
  +    configuration details that the client application must be aware of
  +    (including the name of the SMTP host to be used for message sending).</p>
  +
  +    <p>Tomcat 4 includes a standard resource factory that will create
  +    <code>javax.mail.Session</code> session instances for you, already
  +    connected to the SMTP server that is configured in <code>server.xml</code>.
  +    In this way, the application is totally insulated from changes in the
  +    email server configuration environment - it simply asks for, and receives,
  +    a preconfigured session whenever needed.</p>
  +
  +    <p>The steps required for this are outlined below.</p>
  +
  +    <h3>1.  Declare Your Resource Requirements</h3>
  +
  +    <p>The first thing you should do is modify the web application deployment
  +    descriptor (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under
  +    which you will look up preconfigured sessions.  By convention, all such
  +    names should resolve to the <code>mail</code> subcontext (relative to the
  +    standard <code>java:comp/env</code> naming context that is the root of
  +    all provided resource factories.  A typical <code>web.xml</code> entry
  +    might look like this:</p>
  +<source>
  +&lt;resource-ref&gt;
  +  &lt;description&gt;
  +    Resource reference to a factory for javax.mail.Session
  +    instances that may be used for sending electronic mail
  +    messages, preconfigured to connect to the appropriate
  +    SMTP server.
  +  &lt;/description&gt;
  +  &lt;res-ref-name&gt;
  +    mail/Session
  +  &lt;/res-ref-name&gt;
  +  &lt;res-type&gt;
  +    javax.mail.Session
  +  &lt;/res-type&gt;
  +  &lt;res-auth&gt;
  +    Container
  +  &lt;/res-auth&gt;
  +&lt;/resource-ref&gt;
  +</source>
  +
  +    <p><strong>WARNING</strong> - Be sure you respect the element ordering
  +    that is required by the DTD for web application deployment descriptors!
  +    See the
  +    <a href="http://java.sun.com/products/servlet/download.html">Servlet
  +    Specification</a> for details.</p>
  +
  +    <h3>2.  Code Your Application's Use Of This Resource</h3>
  +
  +    <p>A typical use of this resource reference might look like this:</p>
  +<source>
  +Context initCtx = new InitialContext();
  +Context envCtx = (Context) initCtx.lookup("java:comp/env");
  +Session session = (Session) envCtx.lookup("mail/Session");
  +
  +Message message = new MimeMessage(session);
  +message.setFrom(new InternetAddress(request.getParameter("from"));
  +InternetAddress to[] = new InternetAddress[1];
  +to[0] = new InternetAddress(request.getParameter("to"));
  +message.setRecipients(Message.RecipientType.TO, to);
  +message.setSubject(request.getParameter("subject"));
  +message.setContent(request.getParameter("content"), "text/plain");
  +Transport.send(message);
  +</source>
  +
  +    <p>Note that the application uses the same resource reference name
  +    that was declared in the web application deployment descriptor.  This
  +    is matched up against the resource factory that is configured in
  +    <code>$CATALINA_HOME/conf/server.xml</code>, as described below.</p>
  +
  +    <h3>3.  Configure Tomcat's Resource Factory</h3>
  +
  +    <p>To configure Tomcat's resource factory, add an elements like this to the
  +    <code>$CATALINA_HOME/conf/server.xml</code> file, nested inside the
  +    <code>Context</code> element for this web application (or nested inside
  +    a <code>DefaultContext</code> element for the surrounding
  +    <code>&lt;Host&gt;</code> or <code>&lt;Engine&gt;</code> element.</p>
  +<source>
  +&lt;Context ...&gt;
  +  ...
  +  &lt;Resource name="mail/Session" auth="Container"
  +            type="javax.mail.Session"/&gt;
  +  &lt;ResourceParams name="mail/Session"&gt;
  +    &lt;parameter&gt;
  +      &lt;name&gt;mail.smtp.host&lt;/name&gt;
  +      &lt;value&gt;localhost&lt;/value&gt;
  +    &lt;/parameter&gt;
  +  &lt;/ResourceParams&gt;
  +  ...
  +&lt;/Context&gt;
  +</source>
  +
  +    <p>Note that the resource name (here, <code>mail/Session</code>) must
  +    match the value specified in the web application deployment descriptor.
  +    Customize the value of the <code>mail.smtp.host</code> parameter to
  +    point at the server that provides SMTP service for your network.</p>
  +
  +    <h3>Example Application</h3>
  +
  +    <p>The <code>/examples</code> application included with Tomcat contains
  +    an example of utilizing this resource factory.  It is accessed via the
  +    "JSP Examples" link.  The source code for the servlet that actually
  +    sends the mail message is in
  +    <code>/WEB-INF/classes/SendMailServlet.java</code>.</p>
  +
  +    <p><strong>WARNING</strong> - The default configuration assumes that
  +    there is an SMTP server listing on port 25 on <code>localhost</code>.
  +    If this is not the case, edit the
  +    <code>$CATALINA_HOME/conf/server.xml</code> file, and modify the
  +    parameter value for the <code>mail.smtp.host</code> parameter to be
  +    the host name of an SMTP server on your network.</p>
  +
  +  </subsection>
  +
  +  <subsection name="JDBC Data Sources">
  +
  +    <h3>0.  Introduction</h3>
  +
  +    <p>Many web applications need to access a database via a JDBC driver,
  +    to support the functionality required by that application.  The J2EE
  +    Platform Specification requires J2EE Application Servers to make
  +    available a <em>DataSource</em> implementation (that is, a connection
  +    pool for JDBC connections) for this purpose.  Tomcat 4 offers exactly
  +    the same support, so that database-based applications you develop on
  +    Tomcat using this service will run unchanged on any J2EE server.</p>
  +
  +    <p>For information about JDBC, you should consult the following:</p>
  +    <ul>
  +    <li><a href="http://java.sun.com/products/jdbc/">http://java.sun.com/products/jdbc/</a> -
  +        Home page for information about Java Database Connectivity.</li>
  +    <li><a href="http://java.sun.com/j2se/1.3/docs/guide/jdbc/spec2/jdbc2.1.frame.html">http://java.sun.com/j2se/1.3/docs/guide/jdbc/spec2/jdbc2.1.frame.html</a> -
  +        The JDBC 2.1 API Specification.</li>
  +    <li><a href="http://java.sun.com/products/jdbc/jdbc20.stdext.pdf">http://java.sun.com/products/jdbc/jdbc20.stdext.pdf</a> -
  +        The JDBC 2.0 Standard Extension API (including the
  +        <code>javax.sql.DataSource</code> API).  This package is now known
  +        as the "JDBC Optional Package".</li>
  +    <li><a href="http://java.sun.com/j2ee/download.html">http://java.sun.com/j2ee/download.html</a> -
  +        The J2EE Platform Specification (covers the JDBC facilities that
  +        all J2EE platforms must provide to applications).</li>
  +    </ul>
  +
  +    <p><strong>NOTE</strong> - The default data source support in Tomcat
  +    supports Tyrex.  However, it is possible to use any other connection pool
  +    that implements <code>javax.sql.DataSource</code>, by writing your own
  +    custom resource factory, as described
  +    <a href="#Adding Custom Resource Factories">below</a>.</p>
  +
  +    <h3>1.  Install Your JDBC Driver</h3>
  +
  +    <p>Use of the <em>JDBC Data Sources</em> JNDI Resource Factory requires
  +    that you make an appropriate JDBC driver available to both Tomcat internal
  +    classes and to your web application.  This is most easily accomplished by
  +    installing the driver's JAR file(s) into the
  +    <code>$CATALINA_HOME/common/lib</code> directory, which makes the driver
  +    available both to the resource factory and to your application.</p>
  +
  +    <h3>2.  Declare Your Resource Requirements</h3>
  +
  +    <p>Next, modify the web application deployment descriptor
  +    (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under
  +    which you will look up preconfigured data source.  By convention, all such
  +    names should resolve to the <code>jdbc</code> subcontext (relative to the
  +    standard <code>java:comp/env</code> naming context that is the root of
  +    all provided resource factories.  A typical <code>web.xml</code> entry
  +    might look like this:</p>
  +<source>
  +&lt;resource-ref&gt;
  +  &lt;description&gt;
  +    Resource reference to a factory for java.sql.Connection
  +    instances that may be used for talking to a particular
  +    database that is configured in the server.xml file.
  +  &lt;/description&gt;
  +  &lt;res-ref-name&gt;
  +    jdbc/EmployeDB
  +  &lt;/res-ref-name&gt;
  +  &lt;res-type&gt;
  +    javax.sql.DataSource
  +  &lt;/res-type&gt;
  +  &lt;res-auth&gt;
  +    Container
  +  &lt;/res-auth&gt;
  +&lt;/resource-ref&gt;
  +</source>
  +
  +    <p><strong>WARNING</strong> - Be sure you respect the element ordering
  +    that is required by the DTD for web application deployment descriptors!
  +    See the
  +    <a href="http://java.sun.com/products/servlet/download.html">Servlet
  +    Specification</a> for details.</p>
  +
  +    <h3>3.  Code Your Application's Use Of This Resource</h3>
  +
  +    <p>A typical use of this resource reference might look like this:</p>
  +<source>
  +Context initCtx = new InitialContext();
  +Context envCtx = (Context) initCtx.lookup("java:comp/env");
  +DataSource ds = (DataSource)
  +  envCtx.lookup("jdbc/EmployeeDB");
  +
  +Connection conn = ds.getConnection();
  +... use this connection to access the database ...
  +conn.close();
  +</source>
  +
  +    <p>Note that the application uses the same resource reference name
  +    that was declared in the web application deployment descriptor.  This
  +    is matched up against the resource factory that is configured in
  +    <code>$CATALINA_HOME/conf/server.xml</code>, as described below.</p>
  +
  +    <h3>4.  Configure Tomcat's Resource Factory</h3>
  +
  +    <p>To configure Tomcat's resource factory, add an elements like this to the
  +    <code>$CATALINA_HOME/conf/server.xml</code> file, nested inside the
  +    <code>Context</code> element for this web application (or nested inside
  +    a <code>DefaultContext</code> element for the surrounding
  +    <code>&lt;Host&gt;</code> or <code>&lt;Engine&gt;</code> element.</p>
  +<source>
  +&lt;Context ...&gt;
  +  ...
  +  &lt;Resource name="jdbc/EmployeeDB" auth="Container"
  +            type="javax.sql.DataSource"/&gt;
  +  &lt;ResourceParams name="jdbc/EmployeeDB"&gt;
  +    &lt;parameter&gt;
  +      &lt;name&gt;user&lt;/name&gt;
  +      &lt;value&gt;dbusername&lt;/value&gt;
  +    &lt;/parameter&gt;
  +    &lt;parameter&gt;
  +      &lt;name&gt;password&lt;/name&gt;
  +      &lt;value&gt;dbpassword&lt;/value&gt;
  +    &lt;/parameter&gt;
  +    &lt;parameter&gt;
  +      &lt;name&gt;driverClassName&lt;/name&gt;
  +      &lt;value&gt;org.hsql.jdbcDriver&lt;/value&gt;
  +    &lt;/parameter&gt;
  +    &lt;parameter&gt;
  +      &lt;name&gt;driverName&lt;/name&gt;
  +      &lt;value&gt;jdbc:HypersonicSQL:database&lt;/value&gt;
  +    &lt;/parameter&gt;
  +  &lt;/ResourceParams&gt;
  +  ...
  +&lt;/Context&gt;
  +</source>
  +
  +    <p>Note that the resource name (here, <code>jdbc/EmployeeDB</code>) must
  +    match the value specified in the web application deployment descriptor.
  +    Customize the value of the <code>mail.smtp.host</code> parameter to
  +    point at the server that provides SMTP service for your network.</p>
  +
  +    <p>This example assumes that you are using the HypersonicSQL database
  +    JDBC driver.  Customize the <code>driverClassName</code> and
  +    <code>driverName</code> parameters to match your actual database's
  +    JDBC driver and connection URL.</p>
  +
  +  </subsection>
  +
  +  <subsection name="User Transactions">
  +
  +    <p>If you utilize Tyrex for your JDBC resource factory as described
  +    <a href="#JDBC Data Sources">above</a>, you will also have support for
  +    the <code>java.transaction.UserTransaction</code> resource provided by
  +    Tyrex (since it is XA-capable).  To use this feature, code your
  +    application as follows:</p>
  +<source>
  +Context initCtx = new InitialContext();
  +Context envCtx = (Context) initCtx.lookup("java:comp/env");
  +Transaction tx = (Transaction) envCtx.lookup("UserTransaction");
  +
  +tx.begin();
  +... perform transactional operations on data ...
  +tx.commit();
  +</source>
  +
  +    <p>This is useful when you need to do "two-phased commits" across more
  +    than one database, where the commit needs to either succeed completely
  +    or fail completely across all associated databases.  This feature
  +    requires a JDBC driver that also supports XA capabilities.  See the
  +    J2EE and JDBC documentation for more information.</p>
  +
  +  </subsection>
  +
  +</section>
  +
  +
  +<section name="Adding Custom Resource Factories">
  +
  +  <p>If none of the standard resource factories meet your needs, you can
  +  write your own factory and integrate it into Tomcat 4, and then configure
  +  the use of this factory in the <code>conf/server.xml</code> configuration
  +  file.  In the example below, we will create a factory that only knows how
  +  to create <code>com.mycompany.MyBean</code> beans, from the
  +  <a href="Generic JavaBean Resources">Generic JavaBean Resources</a>
  +  example, above.</p>
  +
  +  <h3>1.  Write A Resource Factory Class</h3>
  +
  +  <p>You must write a class that implements the JNDI service provider
  +  <code>javax.naming.spi.ObjectFactory</code> inteface.  Every time your
  +  web application calls <code>lookup()</code> on a context entry that is
  +  bound to this factory, the <code>getObjectInstance()</code> method is
  +  called, with the following arguments:</p>
  +  <ul>
  +  <li><strong>Object obj</strong> - The (possibly null) object containing
  +      location or reference information that can be used in creating an
  +      object.  For Tomcat, this will always be an object of type
  +      <code>javax.naming.Reference</code>, which contains the class name
  +      of this factory class, as well as the configuration properties
  +      (from <code>conf/server.xml</code>) to use in creating objects
  +      to be returned.</li>
  +  <li><strong>Name name</strong> - The name to which this factory is bound
  +      relative to <code>nameCtx</code>, or <code>null</code> if no name
  +      is specified.</li>
  +  <li><strong>Context nameCtx</strong> - The context relative to which the
  +      <code>name</code> parameter is specified, or <code>null</code> if
  +      <code>name</code> is relative to the default initial context.</li>
  +  <li><strong>Hashtable environment</strong> - The (possibly null)
  +      environment that is used in creating this object.  This is generally
  +      ignored in Tomcat object factories.</li>
  +  </ul>
  +
  +  <p>To create a resource factory that knows how to produce <code>MyBean</code>
  +  instances, you might create a class like this:</p>
  +
  +<source>
  +package com.mycompany;
  +
  +import java.util.Enumeration;
  +import java.util.Hashtable;
  +import javax.naming.Context;
  +import javax.naming.Name;
  +import javax.naming.NamingException;
  +import javax.naming.RefAddr;
  +import javax.naming.Reference;
  +import javax.naming.spi.ObjectFactory;
  +
  +public class MyBeanFactory implements ObjectFactory {
  +
  +  public Object getObjectInstance(Object obj,
  +      Name name, Context nameCtx, Hashtable environment)
  +      throws NamingException {
  +
  +      // Acquire an instance of our specified bean class
  +      MyBean bean = new MyBean();
  +
  +      // Customize the bean properties from our attributes
  +      Reference ref = (Reference) obj;
  +      Enumeration addrs = ref.getAll();
  +      while (addrs.hasMoreElements()) {
  +          RefAddr addr = (RefAddr) addrs.nextElement();
  +          String name = addr.getType();
  +          String value = (String) addr.getContent();
  +          if (name.equals("foo")) {
  +              bean.setFoo(value);
  +          } else if (name.equals("bar")) {
  +              try {
  +                  bean.setBar(Integer.parseInt(value));
  +              } catch (NumberFormatException e) {
  +                  throw new NamingException("Invalid 'bar' value " + value);
  +              }
  +          }
  +      }
  +
  +      // Return the customized instance
  +      return (bean);
  +
  +  }
  +
  +}
  +</source>
  +
  +  <p>In this example, we are unconditionally creating a new instance of
  +  the <code>com.mycompany.MyBean</code> class, and populating its properties
  +  based on the parameters included in the <code>&lt;ResourceParams&gt;</code>
  +  element that configures this factory (see below).  You should note that any
  +  parameter named <code>factory</code> should be skipped - that parameter is
  +  used to specify the name of the factory class itself (in this case,
  +  <code>com.mycompany.MyBeanFactory</code>) rather than a property of the
  +  bean being configured.</p>
  +
  +  <p>For more information about <code>ObjectFactory</code>, see the
  +  <a href="http://java.sun.com/products/jndi/docs.html">JNDI 1.2 Service
  +  Provider Interface (SPI) Specification</a>.</p>
  +
  +  <p>You will need to compile this class against a class path that includes
  +  all of the JAR files in the <code>$CATALINA_HOME/common/lib</code> and
  +  <code>$CATALINA_HOME/server/lib</code> directories.  When you are through,
  +  place the factory class (and the corresponding bean class) unpacked under
  +  <code>$CATALINA_HOME/common/classes</code>, or in a JAR file inside
  +  <code>$CATALINA_HOME/common/lib</code>.  In this way, the required class
  +  files are visible to both Catalina internal resources and your web
  +  application.</p>
  +
  +  <h3>2.  Declare Your Resource Requirements</h3>
  +
  +  <p>Next, modify your web application deployment descriptor
  +  (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under which
  +  you will request new instances of this bean.  The simplest approach is
  +  to use a <code>&lt;resource-env-ref&gt;</code> element, like this:</p>
  +
  +<source>
  +&lt;resource-env-ref&gt;
  +  &lt;description&gt;
  +    Object factory for MyBean instances.
  +  &lt;/description&gt;
  +  &lt;resource-env-ref-name&gt;
  +    bean/MyBeanFactory
  +  &lt;/resource-env-ref-name&gt;
  +  &lt;resource-env-ref-type&gt;
  +    com.mycompany.MyBean
  +  &lt;/resource-env-ref-type&gt;
  +&lt;resource-env-ref&gt;
  +</source>
  +
  +    <p><strong>WARNING</strong> - Be sure you respect the element ordering
  +    that is required by the DTD for web application deployment descriptors!
  +    See the
  +    <a href="http://java.sun.com/products/servlet/download.html">Servlet
  +    Specification</a> for details.</p>
  +
  +  <h3>3.  Code Your Application's Use Of This Resource</h3>
  +
  +  <p>A typical use of this resource environment reference might look
  +  like this:</p>
  +
  +<source>
  +Context initCtx = new InitialContext();
  +Context envCtx = (Context) initCtx.lookup("java:comp/env");
  +MyBean bean = (MyBean) envCtx.lookup("bean/MyBeanFactory");
  +
  +writer.println("foo = " + bean.getFoo() + ", bar = " +
  +               bean.getBar());
  +</source>
  +
  +    <h3>4.  Configure Tomcat's Resource Factory</h3>
  +
  +    <p>To configure Tomcat's resource factory, add an elements like this to the
  +    <code>$CATALINA_HOME/conf/server.xml</code> file, nested inside the
  +    <code>Context</code> element for this web application (or nested inside
  +    a <code>DefaultContext</code> element for the surrounding
  +    <code>&lt;Host&gt;</code> or <code>&lt;Engine&gt;</code> element.</p>
  +<source>
  +&lt;Context ...&gt;
  +  ...
  +  &lt;Resource name="bean/MyBeanFactory" auth="Container"
  +            type="com.mycompany.MyBean"/&gt;
  +  &lt;ResourceParams name="bean/MyBeanFactory"&gt;
  +    &lt;parameter&gt;
  +      &lt;name&gt;factory&lt;/name&gt;
  +      &lt;value&gt;com.mycompany.MyBeanFactory&lt;/value&gt;
  +    &lt;/parameter&gt;
  +    &lt;parameter&gt;
  +      &lt;name&gt;bar&lt;/name&gt;
  +      &lt;value&gt;23&lt;/value&gt;
  +    &lt;/parameter&gt;
  +  &lt;/ResourceParams&gt;
  +  ...
  +&lt;/Context&gt;
  +</source>
  +
  +    <p>Note that the resource name (here, <code>bean/MyBeanFactory</code>
  +    must match the value specified in the web application deployment
  +    descriptor.  We are also initializing the value of the <code>bar</code>
  +    property, which will cause <code>setBar(23)</code> to be called before
  +    the new bean is returned.  Because we are not initializing the
  +    <code>foo</code> property (although we could have), the bean will
  +    contain whatever default value is set up by its constructor.</p>
  +
  +    <p>You will also note that, from the application developer's perspective,
  +    the declaration of the resource environment reference, and the programming
  +    used to request new instances, is identical to the approach used for the
  +    <em>Generic JavaBean Resources</em> example.  This illustrates one of the
  +    advantages of using JNDI resources to encapsulate functionality - you can
  +    change the underlying implementation without necessarily having to
  +    modify applications using the resources, as long as you maintain
  +    compatible APIs.</p>
  +
  +</section>
  +
  +
  +
  +</body>
  +
  +</document>
  
  
  
  1.5       +466 -466  jakarta-tomcat-4.0/webapps/tomcat-docs/manager-howto.xml
  
  Index: manager-howto.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/manager-howto.xml,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- manager-howto.xml	2001/09/14 20:08:01	1.4
  +++ manager-howto.xml	2001/11/12 21:03:49	1.5
  @@ -1,466 +1,466 @@
  -<?xml version="1.0"?>
  -<!DOCTYPE document [
  -  <!ENTITY project SYSTEM "project.xml">
  -]>
  -<document>
  -
  -    &project;
  -
  -    <properties>
  -        <author email="craigmcc@apache.org">Craig R. McClanahan</author>
  -        <title>Manager App HOW-TO</title>
  -    </properties>
  -
  -<body>
  -
  -
  -<section name="Introduction">
  -
  -<p>In many production environments, it is very useful to have the capability
  -to deploy a new web application, or undeploy an existing one, without having
  -to shut down and restart the entire container.  In addition, you can request
  -an existing application to reload itself, even if you have not declared it
  -to be <code>reloadable</code> in the Tomcat 4 server
  -configuration file.</p>
  -
  -<p>To support these capabilities, Tomcat 4 includes a web application
  -(installed by default on context path <code>/manager</code>) that supports
  -the following functions:</p>
  -<ul>
  -<li>Deploy a new web application, on a specified context path, from a
  -    specified directory or WAR file pathname.</li>
  -<li>List the currently deployed web applications, as well as the
  -    sessions that are currently active for those web apps.</li>
  -<li>Cause an existing application to be reloaded.</li>
  -<li>Undeploy an existing web application.</li>
  -<li>Stop an existing application (so that it becomes unavailable), but
  -    do not undeploy it.</li>
  -<li>Start a stopped application (thus making it available again).</li>
  -</ul>
  -
  -<p>Since <code>Manager</code> is itself a web application, it interacts with
  -you using standard HTTP requests and responses.  However, it's "user interface"
  -is minimal, because it is intended to be accessed from scripts set up by the
  -system administrator.  For this reason, commands are given as part of the
  -request URI, and responses are in the form of simple text that can be easily
  -parsed and processed.</p>
  -
  -<p>Future versions of Tomcat 4 will include administrative functionality that
  -is presented in (at least) the following forms:</p>
  -<ul>
  -<li>As web services, so that Tomcat administration can be easily integrated
  -    into remote and/or non-Java mnagement environments.</li>
  -<li>As a web application with a nice user interface (built on top of the
  -    web services processing layer) for easy Tomcat administration via a
  -    web browser.</li>
  -</ul>
  -
  -</section>
  -
  -<section name="Configuring Manager Application Access">
  -
  -    <blockquote><em>
  -    <p>The description below uses the variable name $CATALINA_HOME
  -    to refer to the directory into which you have installed Tomcat 4,
  -    and is the base directory against which most relative paths are
  -    resolved.  However, if you have configured Tomcat 4 for multiple
  -    instances by setting a CATALINA_BASE directory, you should use
  -    $CATALINA_BASE instead of $CATALINA_HOME for each of these
  -    references.</p>
  -    </em></blockquote>
  -
  -<p>It would be quite unsafe to ship Tomcat with default settings that allowed
  -anyone on the Internet to execute the Manager application on your server.
  -Therefore, the Manager application is shipped with the requirement that anyone
  -who attempts to use it must authenticate themselves, using a username and
  -password that have the role <strong>manager</strong> associated with them.
  -Further, there is no username in the default users file
  -(<conf>$CATALINA_HOME/conf/tomcat-users.xml</conf>) that is assigned this
  -role.  Therefore, access to the Manager application is completely disabled
  -by default.</p>
  -
  -<p>To enable access to the Manager web application, you must either create
  -a new username/password combination and associate the role name
  -<strong>manager</strong> with it, or add the <strong>manager</strong> role
  -to some existing username/password combination.  Exactly where this is done
  -depends on which <code>Realm</code> implementation you are using:</p>
  -<ul>
  -<li><em>MemoryRealm</em> - If you have not customized your
  -    <code>$CATALINA_HOME/conf/server.xml</code> to select a different one,
  -    Tomcat 4 defaults to an XML-format file stored at
  -    <code>$CATALINA_HOME/conf/tomcat-users.xml</code>, which can be
  -    edited with any text editor.  This file contains an XML
  -    <code>&lt;user&gt;</code> for each individual user, which might
  -    look something like this:
  -<source>
  -&lt;user name="craigmcc" password="secret" roles="standard,manager"&gt;
  -</source>
  -    which defines the username and password used by this individual to
  -    log on, and the role names he or she is associated with.  You can
  -    add the <strong>manager</strong> role to the comma-delimited
  -    <code>roles</code> attriute for one or more existing users, and/or
  -    create new users with that assigned role.</li>
  -<li><em>JDBCRealm</em> - Your user and role information is stored in
  -    a database accessed via JDBC.  Add the <strong>manager</strong> role
  -    to one or more existing users, and/or create one or more new users
  -    with this role assigned, following the standard procedures for your
  -    environment.</li>
  -<li><em>JNDIRealm</em> - Your user and role information is stored in
  -    a directory server accessed via LDAP.  Add the <strong>manager</strong>
  -    role to one or more existing users, and/or create one or more new users
  -    with this role assigned, following the standard procedures for your
  -    environment.</li>
  -</ul>
  -
  -<p>The first time you attempt to issue one of the Manager commands
  -described in the next section, you will be challenged to logn on, using
  -BASIC authentication.  The username and password you enter do not matter,
  -as long as they identify a valid user in the users database who possesses
  -the role <strong>manager</strong>.</p>
  -
  -</section>
  -
  -
  -<section name="Supported Manager Commands">
  -
  -<p>All commands that the Manager application knows how to process are
  -specified in a single request URI like this:</p>
  -<source>
  -http://{host}:{port}/manager/{command}?{parameters}
  -</source>
  -<p>where <code>{host}</code> and <code>{port}</code> represent the hostname
  -and port number on which Tomcat is running, <code>{command}</code>
  -represents the Manager command you wish to execute, and
  -<code>{parameters}</code> represents the query parameters
  -that are specific to that command.  In the illustrations below, customize
  -the host and port appropriately for your installation.</p>
  -
  -<p>Most commands accept one or more of the following query parameters:</p>
  -<ul>
  -<li><strong>path</strong> - The context path (including the leading slash)
  -    of the web application you are dealing with.  To select the ROOT web
  -    application, specify a zero-length string.  <strong>NOTE</strong> -
  -    It is not possible to perform administrative commands on the
  -    Manager application itself.</li>
  -<li><strong>war</strong> - URL of a web application archive (WAR) file,
  -    or pathname of a directory, that contains the web application.
  -    You can use URLs in any of the following formats:
  -    <ul>
  -    <li><strong>file:/absolute/path/to/a/directory</strong> - The absolute
  -        path of a directory that contains the unpacked version of a web
  -        application.  This directory will be attached to the context path
  -        you specify without any changes.</li>
  -    <li><strong>jar:file:/absolute/path/to/a/warfile.war!/</strong> - The
  -        URL to a local web application archive (WAR) file.  You can use any
  -        syntax that is valid for the <code>JarURLConnection</code> class
  -        for reference to an entire JAR file.</li>
  -    <li><strong>jar:http://hostname:port/path/to/a/warfile.war!/</strong> -
  -        You can also deploy web applications from a remote JAR file.  You can
  -        use any syntax that is valid for the <code>JarURLConnection</code>
  -        class for reference to an entire JAR file.</li>
  -    </ul></li>
  -</ul>
  -
  -<p>Each command will return a response in <code>text/plain</code> format
  -(i.e. plain ASCII with no HTML markup), making it easy for both humans and
  -programs to read).  The first line of the response wil begin with either
  -<code>OK</code> or <code>FAIL</code>, indicating whether the requested
  -command was successful or not.  In the case of failure, the rest of the first
  -line will contain a description of the problem that was encountered.  Some
  -commands include additional lines of information as described below.</p>
  -
  -<p><em>Internationalization Note</em> - The Manager application looks up
  -its message strings in resource bundles, so it is possible that the strings
  -have been translated for your platform.  The examples below show the English
  -version of the messages.</p>
  -
  -<subsection name="Deploy A New Application">
  -
  -<source>
  -http://localhost:8080/manager/install?path=/foo&amp;war=file:/path/to/foo
  -
  -http://localhost:8080/manager/install?path=/bar&amp;war=jar:file:/path/to/bar.war!/
  -</source>
  -
  -<p>Install and start a new web application, attached to the specified context
  -path (which must not be in use by any other web application).  The
  -<code>war</code> parameter specifies a URL (including the <code>file:</code>
  -scheme) for either a directory or a web application archive (WAR) file.
  -The supported syntax for a URL referring to a WAR file is described on the
  -Javadocs page for the <code>java.net.JarURLConnection</code> class.  Use
  -only URLs that refer to the entire WAR file.</p>
  -
  -<p>If installation and startup is successful, you will receive a response
  -like this:</p>
  -<source>
  -OK - Installed application at context path /foo
  -</source>
  -
  -<p>Otherwise, the response will start with <code>FAIL</code> and include an
  -error message.  Possible causes for problems include:</p>
  -<ul>
  -<li><em>Application already exists at path /foo</em>
  -    <blockquote>
  -    <p>The context paths for all currently running web applications must be
  -    unique.  Therefore, you must either undeploy the existing web application
  -    using this context path, or choose a different context path for the
  -    new one.</p>
  -    </blockquote></li>
  -<li><em>Document base does not exist or is not a readable directory</em>
  -    <blockquote>
  -    <p>The URL specified by the <code>war</code> parameter must identify a
  -    directory on this server that contains the "unpacked" version of a
  -    web application, or the absolute URL of a web application archive (WAR)
  -    file that contains this application.  Correct the value specified by
  -    the <code>war</code> parameter.</p>
  -    </blockquote></li>
  -<li><em>Encountered exception</em>
  -    <blockquote>
  -    <p>An exception was encountered trying to start the new web application.
  -    Check the Tomcat 4 logs for the details, but likely explanations include
  -    problems parsing your <code>/WEB-INF/web.xml</code> file, or missing
  -    classes encountered when initializing application event listeners and
  -    filters.</p>
  -    </blockquote></li>
  -<li><em>Invalid application URL was specified</em>
  -    <blockquote>
  -    <p>The URL for the directory or web application that you specified
  -    was not valid.  Such URLs must start with <code>file:</code>, and URLs
  -    for a WAR file must end in ".war".</p>
  -    </blockquote></li>
  -<li><em>Invalid context path was specified</em>
  -    <blockquote>
  -    <p>The context path must start with a slash character, unless you are
  -    referencing the ROOT web application -- in which case the context path
  -    must be a zero-length string.</p>
  -    </blockquote></li>
  -<li><em>No context path was specified</em>
  -    <blockquote>
  -    The <code>path</code> parameter is required.
  -    </blockquote></li>
  -</ul>
  -
  -</subsection>
  -
  -<subsection name="List Currently Deployed Applications">
  -
  -<source>
  -http://localhost:8080/manager/list
  -</source>
  -
  -<p>List the context paths, current status (<code>running</code> or
  -<code>stopped</code>), and number of active sessions for all currently
  -deployed web applications.  A typical response immediately after starting
  -Tomcat might look like this:</p>
  -<source>
  -OK - Listed applications for virtual host localhost
  -/webdav:running:0
  -/examples:running:0
  -/manager:running:0
  -/:running:0
  -</source>
  -
  -</subsection>
  -
  -<subsection name="Reload An Existing Application">
  -
  -<source>
  -http://localhost:8080/manager/reload?path=/examples
  -</source>
  -
  -<p>Signal an existing application to shut itself down and reload.  This can
  -be useful when you've recompiled classes on an application that is not
  -configured with the <code>reloadable="true"</code> attribute in its
  -<code>&lt;Context&gt;</code> entry in
  -<code>$CATALINA_HOME/conf/server.xml</code>, or when you've made other
  -changes (such as to <code>conf/web.xml</code>) that are not automatically
  -recognized by Tomcat.</p>
  -
  -<p>If this command succeeds, you will see a response like this:</p>
  -<source>
  -OK - Reloaded application at context path /examples
  -</source>
  -
  -<p>Otherwise, the response will start with <code>FAIL</code> and include an
  -error message.  Possible causes for problems include:</p>
  -<ul>
  -<li><em>Encountered exception</em>
  -    <blockquote>
  -    <p>An exception was encountered trying to restart the web application.
  -    Check the Tomcat 4 logs for the details.</p>
  -    </blockquote></li>
  -<li><em>Invalid context path was specified</em>
  -    <blockquote>
  -    <p>The context path must start with a slash character, unless you are
  -    referencing the ROOT web application -- in which case the context path
  -    must be a zero-length string.</p>
  -    </blockquote></li>
  -<li><em>No context exists for path /foo</em>
  -    <blockquote>
  -    <p>There is no deployed application on the context path that you
  -    specified.</p>
  -    </blockquote></li>
  -<li><em>No context path was specified</em>
  -    <blockquote>
  -    The <code>path</code> parameter is required.
  -    </blockquote></li>
  -</ul>
  -
  -</subsection>
  -
  -<subsection name="Session Statistics">
  -
  -<source>
  -http://localhost:8080/manager/sessions?path=/examples
  -</source>
  -
  -<p>Display the default session timeout for a web application, and the
  -number of currently active sessions that fall within ten-minute ranges of
  -their actual timeout times.  For example, after restarting Tomcat and then
  -executing one of the JSP samples in the <code>/examples</code> web app,
  -you might get something like this:</p>
  -<source>
  -OK - Session information for application at context path /examples
  -Default maximum session inactive interval 30 minutes
  -30 - &lt;40 minutes:1 sessions
  -</source>
  -
  -</subsection>
  -
  -
  -<subsection name="Start an Existing Application">
  -
  -<source>
  -http://localhost:8080/manager/start?path=/examples
  -</source>
  -
  -<p>Signal a stopped application to restart, and make itself available again.
  -Stopping and starting is useful, for example, if the database required by
  -your application becomes temporarily unavailable.  It is usually better to
  -stop the web application that relies on this database, rather than letting
  -users continuously encounter database exceptions.</p>
  -
  -<p>If this command succeeds, you will see a response like this:</p>
  -<source>
  -OK - Started application at context path /examples
  -</source>
  -
  -<p>Otherwise, the response will start with <code>FAIL</code> and include an
  -error message.  Possible causes for problems include:</p>
  -<ul>
  -<li><em>Encountered exception</em>
  -    <blockquote>
  -    <p>An exception was encountered trying to undeploy the web application.
  -    Check the Tomcat 4 logs for the details.</p>
  -    </blockquote></li>
  -<li><em>Invalid context path was specified</em>
  -    <blockquote>
  -    <p>The context path must start with a slash character, unless you are
  -    referencing the ROOT web application -- in which case the context path
  -    must be a zero-length string.</p>
  -    </blockquote></li>
  -<li><em>No context exists for path /foo</em>
  -    <blockquote>
  -    <p>There is no deployed application on the context path that you
  -    specified.</p>
  -    </blockquote></li>
  -<li><em>No context path was specified</em>
  -    <blockquote>
  -    The <code>path</code> parameter is required.
  -    </blockquote></li>
  -</ul>
  -
  -</subsection>
  -
  -<subsection name="Stop an Existing Application">
  -
  -<source>
  -http://localhost:8080/manager/stop?path=/examples
  -</source>
  -
  -<p>Signal an existing application to make itself unavailable, but leave it
  -deployed.  Any request that comes in while an application is stopped will
  -see an HTTP error 404, and this application will show as "stopped" on a
  -list applications command.</p>
  -
  -<p>If this command succeeds, you will see a response like this:</p>
  -<source>
  -OK - Stopped application at context path /examples
  -</source>
  -
  -<p>Otherwise, the response will start with <code>FAIL</code> and include an
  -error message.  Possible causes for problems include:</p>
  -<ul>
  -<li><em>Encountered exception</em>
  -    <blockquote>
  -    <p>An exception was encountered trying to undeploy the web application.
  -    Check the Tomcat 4 logs for the details.</p>
  -    </blockquote></li>
  -<li><em>Invalid context path was specified</em>
  -    <blockquote>
  -    <p>The context path must start with a slash character, unless you are
  -    referencing the ROOT web application -- in which case the context path
  -    must be a zero-length string.</p>
  -    </blockquote></li>
  -<li><em>No context exists for path /foo</em>
  -    <blockquote>
  -    <p>There is no deployed application on the context path that you
  -    specified.</p>
  -    </blockquote></li>
  -<li><em>No context path was specified</em>
  -    <blockquote>
  -    The <code>path</code> parameter is required.
  -    </blockquote></li>
  -</ul>
  -
  -</subsection>
  -
  -
  -<subsection name="Undeploy an Existing Application">
  -
  -<source>
  -http://localhost:8080/manager/remove?path=/examples
  -</source>
  -
  -<p>Signal an existing application to gracefully shut itself down, and then
  -remove it from Tomcat (which also makes this context path available for
  -reuse later).</p>
  -
  -<p>If this command succeeds, you will see a response like this:</p>
  -<source>
  -OK - Removed application at context path /examples
  -</source>
  -
  -<p>Otherwise, the response will start with <code>FAIL</code> and include an
  -error message.  Possible causes for problems include:</p>
  -<ul>
  -<li><em>Encountered exception</em>
  -    <blockquote>
  -    <p>An exception was encountered trying to undeploy the web application.
  -    Check the Tomcat 4 logs for the details.</p>
  -    </blockquote></li>
  -<li><em>Invalid context path was specified</em>
  -    <blockquote>
  -    <p>The context path must start with a slash character, unless you are
  -    referencing the ROOT web application -- in which case the context path
  -    must be a zero-length string.</p>
  -    </blockquote></li>
  -<li><em>No context exists for path /foo</em>
  -    <blockquote>
  -    <p>There is no deployed application on the context path that you
  -    specified.</p>
  -    </blockquote></li>
  -<li><em>No context path was specified</em>
  -    <blockquote>
  -    The <code>path</code> parameter is required.
  -    </blockquote></li>
  -</ul>
  -
  -</subsection>
  -
  -</section>
  -
  -
  -</body>
  -
  -</document>
  +<?xml version="1.0"?>
  +<!DOCTYPE document [
  +  <!ENTITY project SYSTEM "project.xml">
  +]>
  +<document>
  +
  +    &project;
  +
  +    <properties>
  +        <author email="craigmcc@apache.org">Craig R. McClanahan</author>
  +        <title>Manager App HOW-TO</title>
  +    </properties>
  +
  +<body>
  +
  +
  +<section name="Introduction">
  +
  +<p>In many production environments, it is very useful to have the capability
  +to deploy a new web application, or undeploy an existing one, without having
  +to shut down and restart the entire container.  In addition, you can request
  +an existing application to reload itself, even if you have not declared it
  +to be <code>reloadable</code> in the Tomcat 4 server
  +configuration file.</p>
  +
  +<p>To support these capabilities, Tomcat 4 includes a web application
  +(installed by default on context path <code>/manager</code>) that supports
  +the following functions:</p>
  +<ul>
  +<li>Deploy a new web application, on a specified context path, from a
  +    specified directory or WAR file pathname.</li>
  +<li>List the currently deployed web applications, as well as the
  +    sessions that are currently active for those web apps.</li>
  +<li>Cause an existing application to be reloaded.</li>
  +<li>Undeploy an existing web application.</li>
  +<li>Stop an existing application (so that it becomes unavailable), but
  +    do not undeploy it.</li>
  +<li>Start a stopped application (thus making it available again).</li>
  +</ul>
  +
  +<p>Since <code>Manager</code> is itself a web application, it interacts with
  +you using standard HTTP requests and responses.  However, it's "user interface"
  +is minimal, because it is intended to be accessed from scripts set up by the
  +system administrator.  For this reason, commands are given as part of the
  +request URI, and responses are in the form of simple text that can be easily
  +parsed and processed.</p>
  +
  +<p>Future versions of Tomcat 4 will include administrative functionality that
  +is presented in (at least) the following forms:</p>
  +<ul>
  +<li>As web services, so that Tomcat administration can be easily integrated
  +    into remote and/or non-Java mnagement environments.</li>
  +<li>As a web application with a nice user interface (built on top of the
  +    web services processing layer) for easy Tomcat administration via a
  +    web browser.</li>
  +</ul>
  +
  +</section>
  +
  +<section name="Configuring Manager Application Access">
  +
  +    <blockquote><em>
  +    <p>The description below uses the variable name $CATALINA_HOME
  +    to refer to the directory into which you have installed Tomcat 4,
  +    and is the base directory against which most relative paths are
  +    resolved.  However, if you have configured Tomcat 4 for multiple
  +    instances by setting a CATALINA_BASE directory, you should use
  +    $CATALINA_BASE instead of $CATALINA_HOME for each of these
  +    references.</p>
  +    </em></blockquote>
  +
  +<p>It would be quite unsafe to ship Tomcat with default settings that allowed
  +anyone on the Internet to execute the Manager application on your server.
  +Therefore, the Manager application is shipped with the requirement that anyone
  +who attempts to use it must authenticate themselves, using a username and
  +password that have the role <strong>manager</strong> associated with them.
  +Further, there is no username in the default users file
  +(<conf>$CATALINA_HOME/conf/tomcat-users.xml</conf>) that is assigned this
  +role.  Therefore, access to the Manager application is completely disabled
  +by default.</p>
  +
  +<p>To enable access to the Manager web application, you must either create
  +a new username/password combination and associate the role name
  +<strong>manager</strong> with it, or add the <strong>manager</strong> role
  +to some existing username/password combination.  Exactly where this is done
  +depends on which <code>Realm</code> implementation you are using:</p>
  +<ul>
  +<li><em>MemoryRealm</em> - If you have not customized your
  +    <code>$CATALINA_HOME/conf/server.xml</code> to select a different one,
  +    Tomcat 4 defaults to an XML-format file stored at
  +    <code>$CATALINA_HOME/conf/tomcat-users.xml</code>, which can be
  +    edited with any text editor.  This file contains an XML
  +    <code>&lt;user&gt;</code> for each individual user, which might
  +    look something like this:
  +<source>
  +&lt;user name="craigmcc" password="secret" roles="standard,manager"&gt;
  +</source>
  +    which defines the username and password used by this individual to
  +    log on, and the role names he or she is associated with.  You can
  +    add the <strong>manager</strong> role to the comma-delimited
  +    <code>roles</code> attriute for one or more existing users, and/or
  +    create new users with that assigned role.</li>
  +<li><em>JDBCRealm</em> - Your user and role information is stored in
  +    a database accessed via JDBC.  Add the <strong>manager</strong> role
  +    to one or more existing users, and/or create one or more new users
  +    with this role assigned, following the standard procedures for your
  +    environment.</li>
  +<li><em>JNDIRealm</em> - Your user and role information is stored in
  +    a directory server accessed via LDAP.  Add the <strong>manager</strong>
  +    role to one or more existing users, and/or create one or more new users
  +    with this role assigned, following the standard procedures for your
  +    environment.</li>
  +</ul>
  +
  +<p>The first time you attempt to issue one of the Manager commands
  +described in the next section, you will be challenged to logn on, using
  +BASIC authentication.  The username and password you enter do not matter,
  +as long as they identify a valid user in the users database who possesses
  +the role <strong>manager</strong>.</p>
  +
  +</section>
  +
  +
  +<section name="Supported Manager Commands">
  +
  +<p>All commands that the Manager application knows how to process are
  +specified in a single request URI like this:</p>
  +<source>
  +http://{host}:{port}/manager/{command}?{parameters}
  +</source>
  +<p>where <code>{host}</code> and <code>{port}</code> represent the hostname
  +and port number on which Tomcat is running, <code>{command}</code>
  +represents the Manager command you wish to execute, and
  +<code>{parameters}</code> represents the query parameters
  +that are specific to that command.  In the illustrations below, customize
  +the host and port appropriately for your installation.</p>
  +
  +<p>Most commands accept one or more of the following query parameters:</p>
  +<ul>
  +<li><strong>path</strong> - The context path (including the leading slash)
  +    of the web application you are dealing with.  To select the ROOT web
  +    application, specify a zero-length string.  <strong>NOTE</strong> -
  +    It is not possible to perform administrative commands on the
  +    Manager application itself.</li>
  +<li><strong>war</strong> - URL of a web application archive (WAR) file,
  +    or pathname of a directory, that contains the web application.
  +    You can use URLs in any of the following formats:
  +    <ul>
  +    <li><strong>file:/absolute/path/to/a/directory</strong> - The absolute
  +        path of a directory that contains the unpacked version of a web
  +        application.  This directory will be attached to the context path
  +        you specify without any changes.</li>
  +    <li><strong>jar:file:/absolute/path/to/a/warfile.war!/</strong> - The
  +        URL to a local web application archive (WAR) file.  You can use any
  +        syntax that is valid for the <code>JarURLConnection</code> class
  +        for reference to an entire JAR file.</li>
  +    <li><strong>jar:http://hostname:port/path/to/a/warfile.war!/</strong> -
  +        You can also deploy web applications from a remote JAR file.  You can
  +        use any syntax that is valid for the <code>JarURLConnection</code>
  +        class for reference to an entire JAR file.</li>
  +    </ul></li>
  +</ul>
  +
  +<p>Each command will return a response in <code>text/plain</code> format
  +(i.e. plain ASCII with no HTML markup), making it easy for both humans and
  +programs to read).  The first line of the response wil begin with either
  +<code>OK</code> or <code>FAIL</code>, indicating whether the requested
  +command was successful or not.  In the case of failure, the rest of the first
  +line will contain a description of the problem that was encountered.  Some
  +commands include additional lines of information as described below.</p>
  +
  +<p><em>Internationalization Note</em> - The Manager application looks up
  +its message strings in resource bundles, so it is possible that the strings
  +have been translated for your platform.  The examples below show the English
  +version of the messages.</p>
  +
  +<subsection name="Deploy A New Application">
  +
  +<source>
  +http://localhost:8080/manager/install?path=/foo&amp;war=file:/path/to/foo
  +
  +http://localhost:8080/manager/install?path=/bar&amp;war=jar:file:/path/to/bar.war!/
  +</source>
  +
  +<p>Install and start a new web application, attached to the specified context
  +path (which must not be in use by any other web application).  The
  +<code>war</code> parameter specifies a URL (including the <code>file:</code>
  +scheme) for either a directory or a web application archive (WAR) file.
  +The supported syntax for a URL referring to a WAR file is described on the
  +Javadocs page for the <code>java.net.JarURLConnection</code> class.  Use
  +only URLs that refer to the entire WAR file.</p>
  +
  +<p>If installation and startup is successful, you will receive a response
  +like this:</p>
  +<source>
  +OK - Installed application at context path /foo
  +</source>
  +
  +<p>Otherwise, the response will start with <code>FAIL</code> and include an
  +error message.  Possible causes for problems include:</p>
  +<ul>
  +<li><em>Application already exists at path /foo</em>
  +    <blockquote>
  +    <p>The context paths for all currently running web applications must be
  +    unique.  Therefore, you must either undeploy the existing web application
  +    using this context path, or choose a different context path for the
  +    new one.</p>
  +    </blockquote></li>
  +<li><em>Document base does not exist or is not a readable directory</em>
  +    <blockquote>
  +    <p>The URL specified by the <code>war</code> parameter must identify a
  +    directory on this server that contains the "unpacked" version of a
  +    web application, or the absolute URL of a web application archive (WAR)
  +    file that contains this application.  Correct the value specified by
  +    the <code>war</code> parameter.</p>
  +    </blockquote></li>
  +<li><em>Encountered exception</em>
  +    <blockquote>
  +    <p>An exception was encountered trying to start the new web application.
  +    Check the Tomcat 4 logs for the details, but likely explanations include
  +    problems parsing your <code>/WEB-INF/web.xml</code> file, or missing
  +    classes encountered when initializing application event listeners and
  +    filters.</p>
  +    </blockquote></li>
  +<li><em>Invalid application URL was specified</em>
  +    <blockquote>
  +    <p>The URL for the directory or web application that you specified
  +    was not valid.  Such URLs must start with <code>file:</code>, and URLs
  +    for a WAR file must end in ".war".</p>
  +    </blockquote></li>
  +<li><em>Invalid context path was specified</em>
  +    <blockquote>
  +    <p>The context path must start with a slash character, unless you are
  +    referencing the ROOT web application -- in which case the context path
  +    must be a zero-length string.</p>
  +    </blockquote></li>
  +<li><em>No context path was specified</em>
  +    <blockquote>
  +    The <code>path</code> parameter is required.
  +    </blockquote></li>
  +</ul>
  +
  +</subsection>
  +
  +<subsection name="List Currently Deployed Applications">
  +
  +<source>
  +http://localhost:8080/manager/list
  +</source>
  +
  +<p>List the context paths, current status (<code>running</code> or
  +<code>stopped</code>), and number of active sessions for all currently
  +deployed web applications.  A typical response immediately after starting
  +Tomcat might look like this:</p>
  +<source>
  +OK - Listed applications for virtual host localhost
  +/webdav:running:0
  +/examples:running:0
  +/manager:running:0
  +/:running:0
  +</source>
  +
  +</subsection>
  +
  +<subsection name="Reload An Existing Application">
  +
  +<source>
  +http://localhost:8080/manager/reload?path=/examples
  +</source>
  +
  +<p>Signal an existing application to shut itself down and reload.  This can
  +be useful when you've recompiled classes on an application that is not
  +configured with the <code>reloadable="true"</code> attribute in its
  +<code>&lt;Context&gt;</code> entry in
  +<code>$CATALINA_HOME/conf/server.xml</code>, or when you've made other
  +changes (such as to <code>conf/web.xml</code>) that are not automatically
  +recognized by Tomcat.</p>
  +
  +<p>If this command succeeds, you will see a response like this:</p>
  +<source>
  +OK - Reloaded application at context path /examples
  +</source>
  +
  +<p>Otherwise, the response will start with <code>FAIL</code> and include an
  +error message.  Possible causes for problems include:</p>
  +<ul>
  +<li><em>Encountered exception</em>
  +    <blockquote>
  +    <p>An exception was encountered trying to restart the web application.
  +    Check the Tomcat 4 logs for the details.</p>
  +    </blockquote></li>
  +<li><em>Invalid context path was specified</em>
  +    <blockquote>
  +    <p>The context path must start with a slash character, unless you are
  +    referencing the ROOT web application -- in which case the context path
  +    must be a zero-length string.</p>
  +    </blockquote></li>
  +<li><em>No context exists for path /foo</em>
  +    <blockquote>
  +    <p>There is no deployed application on the context path that you
  +    specified.</p>
  +    </blockquote></li>
  +<li><em>No context path was specified</em>
  +    <blockquote>
  +    The <code>path</code> parameter is required.
  +    </blockquote></li>
  +</ul>
  +
  +</subsection>
  +
  +<subsection name="Session Statistics">
  +
  +<source>
  +http://localhost:8080/manager/sessions?path=/examples
  +</source>
  +
  +<p>Display the default session timeout for a web application, and the
  +number of currently active sessions that fall within ten-minute ranges of
  +their actual timeout times.  For example, after restarting Tomcat and then
  +executing one of the JSP samples in the <code>/examples</code> web app,
  +you might get something like this:</p>
  +<source>
  +OK - Session information for application at context path /examples
  +Default maximum session inactive interval 30 minutes
  +30 - &lt;40 minutes:1 sessions
  +</source>
  +
  +</subsection>
  +
  +
  +<subsection name="Start an Existing Application">
  +
  +<source>
  +http://localhost:8080/manager/start?path=/examples
  +</source>
  +
  +<p>Signal a stopped application to restart, and make itself available again.
  +Stopping and starting is useful, for example, if the database required by
  +your application becomes temporarily unavailable.  It is usually better to
  +stop the web application that relies on this database, rather than letting
  +users continuously encounter database exceptions.</p>
  +
  +<p>If this command succeeds, you will see a response like this:</p>
  +<source>
  +OK - Started application at context path /examples
  +</source>
  +
  +<p>Otherwise, the response will start with <code>FAIL</code> and include an
  +error message.  Possible causes for problems include:</p>
  +<ul>
  +<li><em>Encountered exception</em>
  +    <blockquote>
  +    <p>An exception was encountered trying to undeploy the web application.
  +    Check the Tomcat 4 logs for the details.</p>
  +    </blockquote></li>
  +<li><em>Invalid context path was specified</em>
  +    <blockquote>
  +    <p>The context path must start with a slash character, unless you are
  +    referencing the ROOT web application -- in which case the context path
  +    must be a zero-length string.</p>
  +    </blockquote></li>
  +<li><em>No context exists for path /foo</em>
  +    <blockquote>
  +    <p>There is no deployed application on the context path that you
  +    specified.</p>
  +    </blockquote></li>
  +<li><em>No context path was specified</em>
  +    <blockquote>
  +    The <code>path</code> parameter is required.
  +    </blockquote></li>
  +</ul>
  +
  +</subsection>
  +
  +<subsection name="Stop an Existing Application">
  +
  +<source>
  +http://localhost:8080/manager/stop?path=/examples
  +</source>
  +
  +<p>Signal an existing application to make itself unavailable, but leave it
  +deployed.  Any request that comes in while an application is stopped will
  +see an HTTP error 404, and this application will show as "stopped" on a
  +list applications command.</p>
  +
  +<p>If this command succeeds, you will see a response like this:</p>
  +<source>
  +OK - Stopped application at context path /examples
  +</source>
  +
  +<p>Otherwise, the response will start with <code>FAIL</code> and include an
  +error message.  Possible causes for problems include:</p>
  +<ul>
  +<li><em>Encountered exception</em>
  +    <blockquote>
  +    <p>An exception was encountered trying to undeploy the web application.
  +    Check the Tomcat 4 logs for the details.</p>
  +    </blockquote></li>
  +<li><em>Invalid context path was specified</em>
  +    <blockquote>
  +    <p>The context path must start with a slash character, unless you are
  +    referencing the ROOT web application -- in which case the context path
  +    must be a zero-length string.</p>
  +    </blockquote></li>
  +<li><em>No context exists for path /foo</em>
  +    <blockquote>
  +    <p>There is no deployed application on the context path that you
  +    specified.</p>
  +    </blockquote></li>
  +<li><em>No context path was specified</em>
  +    <blockquote>
  +    The <code>path</code> parameter is required.
  +    </blockquote></li>
  +</ul>
  +
  +</subsection>
  +
  +
  +<subsection name="Undeploy an Existing Application">
  +
  +<source>
  +http://localhost:8080/manager/remove?path=/examples
  +</source>
  +
  +<p>Signal an existing application to gracefully shut itself down, and then
  +remove it from Tomcat (which also makes this context path available for
  +reuse later).</p>
  +
  +<p>If this command succeeds, you will see a response like this:</p>
  +<source>
  +OK - Removed application at context path /examples
  +</source>
  +
  +<p>Otherwise, the response will start with <code>FAIL</code> and include an
  +error message.  Possible causes for problems include:</p>
  +<ul>
  +<li><em>Encountered exception</em>
  +    <blockquote>
  +    <p>An exception was encountered trying to undeploy the web application.
  +    Check the Tomcat 4 logs for the details.</p>
  +    </blockquote></li>
  +<li><em>Invalid context path was specified</em>
  +    <blockquote>
  +    <p>The context path must start with a slash character, unless you are
  +    referencing the ROOT web application -- in which case the context path
  +    must be a zero-length string.</p>
  +    </blockquote></li>
  +<li><em>No context exists for path /foo</em>
  +    <blockquote>
  +    <p>There is no deployed application on the context path that you
  +    specified.</p>
  +    </blockquote></li>
  +<li><em>No context path was specified</em>
  +    <blockquote>
  +    The <code>path</code> parameter is required.
  +    </blockquote></li>
  +</ul>
  +
  +</subsection>
  +
  +</section>
  +
  +
  +</body>
  +
  +</document>
  
  
  
  1.2       +129 -129  jakarta-tomcat-4.0/webapps/tomcat-docs/proxy-howto.xml
  
  Index: proxy-howto.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/proxy-howto.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- proxy-howto.xml	2001/08/21 02:28:21	1.1
  +++ proxy-howto.xml	2001/11/12 21:03:49	1.2
  @@ -1,129 +1,129 @@
  -<?xml version="1.0"?>
  -<!DOCTYPE document [
  -  <!ENTITY project SYSTEM "project.xml">
  -]>
  -<document>
  -
  -    &project;
  -
  -    <properties>
  -        <author email="craigmcc@apache.org">Craig R. McClanahan</author>
  -        <title>Proxy Support HOW-TO</title>
  -    </properties>
  -
  -<body>
  -
  -
  -<section name="Introduction">
  -
  -<p>Using standard configurations of Tomcat, web applications can ask for
  -the server name and port number to which the request was directed for
  -processing.  When Tomcat is running standalone with the
  -<a href="config/http11.html">HTTP/1.1 Connector</a>, it will generally
  -report the server name specified in the request, and the port number on
  -which the <strong>Connector</strong> is listening.  The two servlet API
  -calls of interest, for this purpose, are:</p>
  -<ul>
  -<li><code>ServletRequest.getServerName()</code></li>
  -<li><code>ServletRequest.getServerPort()</code></li>
  -</ul>
  -
  -<p>When you are running behind a proxy server (or a web server that is
  -configured to behave like a proxy server), you will sometimes prefer to
  -manage the values returned by these calls.  In particular, you will
  -generally want the port number to reflect that specified in the original
  -request, not the one on which the <strong>Connector</strong> itself is
  -listening.  You can use the <code>proxyName</code> and <code>proxyPort</code>
  -attributes on the <code>&lt;Connector&gt;</code> element to configure
  -these values.</p>
  -
  -<p>Proxy support can take many forms.  The following sections describe
  -proxy configurations for several common cases.</p>
  -
  -</section>
  -
  -<section name="Apache 1.3 Proxy Support">
  -
  -<p>Apache 1.3 supports an optional module (<code>mod_proxy</code>) that
  -configures the web server to act as a proxy server.  This can be used to
  -forward requests for a particular web application to a Tomcat 4 instance,
  -without having to configure a web connector such as <code>mod_webapp</code>.
  -To accomplish this, you need to perform the following tasks:</p>
  -<ol>
  -<li>Configure your copy of Apache so that it includes the
  -    <code>mod_proxy</code> module.  If you are building from source,
  -    the easiest way to do this is to include the
  -    <code>--enable-module=proxy</code> directive on the
  -    <code>./configure</code> command line.</li>
  -<li>If not already added for you, make sure that you are loading the
  -    <code>mod_proxy</code> module at Apache startup time, by using the
  -    following directives in your <code>httpd.conf</code> file:
  -<source>
  -LoadModule proxy_module  {path-to-modules}/mod_proxy.so
  -AddModule  mod_proxy.c
  -</source></li>
  -<li>Include two directives in your <code>httpd.conf</code> file for
  -    each web application that you wish to forward to Tomcat 4.  For
  -    example, to forward an application at context path <code>/myapp</code>:
  -<source>
  -ProxyPass         /myapp  http://localhost:8081/myapp
  -ProxyPassReverse  /myapp  http://localhost:8081/myapp
  -</source>
  -    which tells Apache to forward URLs of the form
  -    <code>http://localhost/myapp/*</code> to the Tomcat 4 connector
  -    listening on port 8081.</li>
  -<li>Configure your copy of Tomcat 4 to include a special
  -    <code>&lt;Connector&gt;</code> element, with appropriate
  -    proxy settings, for example:
  -<source>
  -&lt;Connector className="org.apache.catalina.connector.http.HttpConnector"
  -                port="8081" ...
  -           proxyName="www.mycompany.com"
  -           proxyPort="80"/&gt;
  -</source>
  -    which will cause servlets inside this web application to think that
  -    all proxied requests were directed to <code>www.mycompany.com</code>
  -    on port 80.</li>
  -<li>It is legal to omit the <code>proxyName</code> attribute from the
  -    <code>&lt;Connector&gt;</code> element.  If you do so, the value
  -    returned by <code>request.getServerName()</code> will by the host
  -    name on which Tomcat is running.  In the example above, it would be
  -    <code>localhost</code>.</li>
  -<li>If you also have a <code>&lt;Connector&gt;</code> listening on port
  -    8080 (nested within the same <a href="config/service.html">Service</a>
  -    element), the requests to either port will share the same set of
  -    virtual hosts and web applications.</li>
  -<li>You might wish to use the IP filtering features of your operating
  -    system to restrict connections to port 8081 (in this example) to
  -    be allowed <strong>only</strong> from the server that is running
  -    Apache.</li>
  -<li>Alternatively, you can set up a series of web applications that are
  -    only available via proxying, as follows:
  -    <ul>
  -    <li>Configure another <code>&lt;Service&gt;</code> that contains
  -        only a <code>&lt;Connector&gt;</code> for the proxy port.</li>
  -    <li>Configure appropriate <a href="config/engine.html">Engine</a>,
  -        <a href="host.html">Host</a>, and
  -        <a href="context.html">Context</a> elements for the virtual hosts
  -        and web applications accessible via proxying.</li>
  -    <li>Optionally, protect port 8081 with IP filters as described
  -        earlier.</li>
  -    </ul></li>
  -<li>When requests are proxied by Apache, the web server will be recording
  -    these requests in its access log.  Therefore, you will generally want to
  -    disable any access logging performed by Tomcat itself.</li>
  -</ol>
  -
  -<p>When requests are proxied in this manner, <strong>all</strong> requests
  -for the configured web applications will be processed by Tomcat (including
  -requests for static content).  You will often be able to improve performance
  -by using the <code>mod_webapp</code> web connector instead, which
  -automatically configures itself to have Apache handle static content that is
  -not processed by filters or security constraints defined within the web
  -application's deployment descriptor (<code>/WEB-INF/web.xml</code>).</p>
  -
  -</section>
  -
  -</body>
  -
  -</document>
  +<?xml version="1.0"?>
  +<!DOCTYPE document [
  +  <!ENTITY project SYSTEM "project.xml">
  +]>
  +<document>
  +
  +    &project;
  +
  +    <properties>
  +        <author email="craigmcc@apache.org">Craig R. McClanahan</author>
  +        <title>Proxy Support HOW-TO</title>
  +    </properties>
  +
  +<body>
  +
  +
  +<section name="Introduction">
  +
  +<p>Using standard configurations of Tomcat, web applications can ask for
  +the server name and port number to which the request was directed for
  +processing.  When Tomcat is running standalone with the
  +<a href="config/http11.html">HTTP/1.1 Connector</a>, it will generally
  +report the server name specified in the request, and the port number on
  +which the <strong>Connector</strong> is listening.  The two servlet API
  +calls of interest, for this purpose, are:</p>
  +<ul>
  +<li><code>ServletRequest.getServerName()</code></li>
  +<li><code>ServletRequest.getServerPort()</code></li>
  +</ul>
  +
  +<p>When you are running behind a proxy server (or a web server that is
  +configured to behave like a proxy server), you will sometimes prefer to
  +manage the values returned by these calls.  In particular, you will
  +generally want the port number to reflect that specified in the original
  +request, not the one on which the <strong>Connector</strong> itself is
  +listening.  You can use the <code>proxyName</code> and <code>proxyPort</code>
  +attributes on the <code>&lt;Connector&gt;</code> element to configure
  +these values.</p>
  +
  +<p>Proxy support can take many forms.  The following sections describe
  +proxy configurations for several common cases.</p>
  +
  +</section>
  +
  +<section name="Apache 1.3 Proxy Support">
  +
  +<p>Apache 1.3 supports an optional module (<code>mod_proxy</code>) that
  +configures the web server to act as a proxy server.  This can be used to
  +forward requests for a particular web application to a Tomcat 4 instance,
  +without having to configure a web connector such as <code>mod_webapp</code>.
  +To accomplish this, you need to perform the following tasks:</p>
  +<ol>
  +<li>Configure your copy of Apache so that it includes the
  +    <code>mod_proxy</code> module.  If you are building from source,
  +    the easiest way to do this is to include the
  +    <code>--enable-module=proxy</code> directive on the
  +    <code>./configure</code> command line.</li>
  +<li>If not already added for you, make sure that you are loading the
  +    <code>mod_proxy</code> module at Apache startup time, by using the
  +    following directives in your <code>httpd.conf</code> file:
  +<source>
  +LoadModule proxy_module  {path-to-modules}/mod_proxy.so
  +AddModule  mod_proxy.c
  +</source></li>
  +<li>Include two directives in your <code>httpd.conf</code> file for
  +    each web application that you wish to forward to Tomcat 4.  For
  +    example, to forward an application at context path <code>/myapp</code>:
  +<source>
  +ProxyPass         /myapp  http://localhost:8081/myapp
  +ProxyPassReverse  /myapp  http://localhost:8081/myapp
  +</source>
  +    which tells Apache to forward URLs of the form
  +    <code>http://localhost/myapp/*</code> to the Tomcat 4 connector
  +    listening on port 8081.</li>
  +<li>Configure your copy of Tomcat 4 to include a special
  +    <code>&lt;Connector&gt;</code> element, with appropriate
  +    proxy settings, for example:
  +<source>
  +&lt;Connector className="org.apache.catalina.connector.http.HttpConnector"
  +                port="8081" ...
  +           proxyName="www.mycompany.com"
  +           proxyPort="80"/&gt;
  +</source>
  +    which will cause servlets inside this web application to think that
  +    all proxied requests were directed to <code>www.mycompany.com</code>
  +    on port 80.</li>
  +<li>It is legal to omit the <code>proxyName</code> attribute from the
  +    <code>&lt;Connector&gt;</code> element.  If you do so, the value
  +    returned by <code>request.getServerName()</code> will by the host
  +    name on which Tomcat is running.  In the example above, it would be
  +    <code>localhost</code>.</li>
  +<li>If you also have a <code>&lt;Connector&gt;</code> listening on port
  +    8080 (nested within the same <a href="config/service.html">Service</a>
  +    element), the requests to either port will share the same set of
  +    virtual hosts and web applications.</li>
  +<li>You might wish to use the IP filtering features of your operating
  +    system to restrict connections to port 8081 (in this example) to
  +    be allowed <strong>only</strong> from the server that is running
  +    Apache.</li>
  +<li>Alternatively, you can set up a series of web applications that are
  +    only available via proxying, as follows:
  +    <ul>
  +    <li>Configure another <code>&lt;Service&gt;</code> that contains
  +        only a <code>&lt;Connector&gt;</code> for the proxy port.</li>
  +    <li>Configure appropriate <a href="config/engine.html">Engine</a>,
  +        <a href="host.html">Host</a>, and
  +        <a href="context.html">Context</a> elements for the virtual hosts
  +        and web applications accessible via proxying.</li>
  +    <li>Optionally, protect port 8081 with IP filters as described
  +        earlier.</li>
  +    </ul></li>
  +<li>When requests are proxied by Apache, the web server will be recording
  +    these requests in its access log.  Therefore, you will generally want to
  +    disable any access logging performed by Tomcat itself.</li>
  +</ol>
  +
  +<p>When requests are proxied in this manner, <strong>all</strong> requests
  +for the configured web applications will be processed by Tomcat (including
  +requests for static content).  You will often be able to improve performance
  +by using the <code>mod_webapp</code> web connector instead, which
  +automatically configures itself to have Apache handle static content that is
  +not processed by filters or security constraints defined within the web
  +application's deployment descriptor (<code>/WEB-INF/web.xml</code>).</p>
  +
  +</section>
  +
  +</body>
  +
  +</document>
  
  
  
  1.3       +792 -792  jakarta-tomcat-4.0/webapps/tomcat-docs/realm-howto.xml
  
  Index: realm-howto.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/realm-howto.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- realm-howto.xml	2001/09/06 23:06:43	1.2
  +++ realm-howto.xml	2001/11/12 21:03:49	1.3
  @@ -1,792 +1,792 @@
  -<?xml version="1.0"?>
  -<!DOCTYPE document [
  -  <!ENTITY project SYSTEM "project.xml">
  -]>
  -<document>
  -
  -    &project;
  -
  -    <properties>
  -        <author email="craigmcc@apache.org">Craig R. McClanahan</author>
  -        <title>Realm Configuration HOW-TO</title>
  -    </properties>
  -
  -<body>
  -
  -
  -<section name="Quick Start">
  -
  -<p>This document describes how to configure Tomcat to support <em>container
  -managed security</em>, by connecting to an existing "database" of usernames,
  -passwords, and user roles.  You only need to care about this if you are using
  -a web application that includes one or more
  -<code>&lt;security-constraint&gt;</code> elements, and a
  -<code>&lt;login-config&gt;</code> element defining how users are required
  -to authenticate themselves.  If you are not utilizing these features, you can
  -safely skip this document.</p>
  -
  -<p>For fundamental background information about container managed security,
  -see the <a href="http://java.sun.com/products/servlet/download.html">Servlet
  -Specification (Version 2.3)</a>, Section 12.  For a more introductory level
  -document for web application developers as well as administrators, see
  -(<strong>FIXME</strong> - link to backgrounder on container managed security
  -to be provided).</p>
  -
  -<p>For information about utilizing the <em>Single Sign On</em> feature of
  -Tomcat 4 (allowing a user to authenticate themselves once across the entire
  -set of web applications associated with a virtual host), see
  -<a href="config/host.html#Single Sign On">here</a>.</p>
  -
  -</section>
  -
  -
  -<section name="Overview">
  -
  -
  -<subsection name="What is a Realm?">
  -
  -<p>A <strong>Realm</strong> is a "database" of usernames and passwords that
  -identify valid users of a web application (or set of web applications), plus
  -an enumeration of the list of <em>roles</em> associated with each valid user.
  -You can think of roles as similar to <em>groups</em> in Unix-like operating
  -systems, because access to specific web application resources is granted to
  -all users possessing a particular role (rather than enumerating the list of
  -associated usernames).  A particular user can have any number of roles
  -associated with their username.</p>
  -
  -<p>Although the Servlet Specification describes a portable mechanism for
  -applications to <em>declare</em> their security requirements (in the
  -<code>web.xml</code> deployment descriptor), there is no portable API
  -defining the interface between a servlet container and the associated user
  -and role information.  In many cases, however, it is desireable to "connect"
  -a servlet container to some existing authentication database or mechanism
  -that already exists in the production environment.  Therefore, Tomcat 4
  -defines a Java interface (<code>org.apache.catalina.Realm</code>) that
  -can be implemented by "plug in" components to establish this connection.
  -Three standard plug-ins are provided, supporting connection to three different
  -sources of authentication information:</p>
  -<ul>
  -<li><a href="#JDBCRealm">JDBCRealm</a> - Accesses authentication information
  -    stored in a relational database, accessed via a JDBC driver.</li>
  -<li><a href="#JNDIRealm">JNDIRealm</a> - Accesses authentication information
  -    stored in an LDAP based directory server, accessed via a JNDI provider.
  -    </li>
  -<li><a href="#MemoryRealm">MemoryRealm</a> - Accesses authentication
  -    information stored in an in-memory object collection, which is initialized
  -    from an XML document (<code>conf/tomcat-users.xml</code>).</li>
  -</ul>
  -
  -<p>It is also possible to write your own <code>Realm</code> implementation,
  -and integrate it with Tomcat 4.  However, doing this is beyond the scope of
  -this document.  See (<strong>FIXME</strong> - reference to developer stuff)
  -for more information.</p>
  -
  -</subsection>
  -
  -
  -<subsection name="Configuring a Realm">
  -
  -<p>Before getting into the details of the standard Realm implementations, it is
  -important to understand, in general terms, how a Realm is configured.  In
  -general, you will be adding an XML element to your <code>conf/server.xml</code>
  -configuration file, that looks something like this:</p>
  -
  -<source>
  -&lt;Realm className="... class name for this implementation"
  -       ... other attributes for this implementation .../&gt;
  -</source>
  -
  -<p>The <code>&lt;Realm&gt;</code> element can be nested inside one of three
  -different elements, which has a direct impact on the "scope" of that Realm
  -(i.e. which web applications will share the same authentication information):
  -</p>
  -<ul>
  -<li><em>Inside an &lt;Engine&gt; element</em> - This Realm will be shared
  -    across ALL web applications on ALL virtual hosts, UNLESS it is overridden
  -    by a Realm element nested inside a subordinate <code>&lt;Host&gt;</code>
  -    or <code>&lt;Context&gt;</code> element.</li>
  -<li><em>Inside a &lt;Host&gt; element</em> - This Realm will be shared across
  -    ALL web applications for THIS virtual host, UNLESS it is overridden
  -    by a Realm element nested inside a subordinate <code>&lt;Context&gt;</code>
  -    element.</li>
  -<li><em>Inside a &lt;Context&gt; element</em> - This Realm will be used ONLY
  -    for THIS web application.</li>
  -</ul>
  -
  -
  -</subsection>
  -
  -
  -</section>
  -
  -
  -<section name="Standard Realm Implementations">
  -
  -
  -<subsection name="JDBCRealm">
  -
  -<h3>Introduction</h3>
  -
  -<p><strong>JDBCRealm</strong> is an implementation of the Tomcat 4
  -<code>Realm</code> interface that looks up users in a relational database
  -accessed via a JDBC driver.  There is substantial configuration flexibility
  -that lets you adapt to existing table and column names, as long as your
  -database structure conforms to the following requirements:</p>
  -<ul>
  -<li>There must be a table, referenced below as the <em>users</em> table,
  -    that contains one row for every valid user that this <code>Realm</code>
  -    should recognize.</li>
  -<li>The <em>users</em> table must contain at least two columns (it may
  -    contain more if your existing applications required it):
  -    <ul>
  -    <li>Username to be recognized by Tomcat when the user logs in.</li>
  -    <li>Password to be recognized by Tomcat when the user logs in.
  -        This value may in cleartext or digested - see below for more
  -        information.</li>
  -    </ul></li>
  -<li>There must be a table, referenced below as the <em>user roles</em> table,
  -    that contains one row for every valid role that is assigned to a
  -    particular user.  It is legal for a user to have zero, one, or more than
  -    one valid role.</li>
  -<li>The <em>user roles</em> table must contain at least two columns (it may
  -    contain more if your existing applications required it):
  -    <ul>
  -    <li>Username to be recognized by Tomcat (same value as is specified
  -        in the <em>users</em> table).</li>
  -    <li>Role name of a valid role associated with this user.</li>
  -    </ul></li>
  -</ul>
  -
  -<h3>Quick Start</h3>
  -
  -<p>To set up Tomcat to use JDBCRealm, you will need to follow these steps:</p>
  -<ol>
  -<li>If you have not yet done so, create tables and columns in your database
  -    that conform to the requirements described above.</li>
  -<li>Configure a database username and password for use by Tomcat, that has
  -    at least read only access to the tables described above.  (Tomcat will
  -    never attempt to write to these tables.)</li>
  -<li>Place a copy of the JDBC driver you will be using inside the
  -    <code>$CATALINA_HOME/server/lib</code> directory (if you do not need it
  -    visible to web applications) or <code>$CATALINA_HOME/common/lib</code>
  -    (if it will be used both by Tomcat 4 <em>and</em> by your apps).
  -    Note that <strong>only</strong> JAR files are recognized!</li>
  -<li>Set up a <code>&lt;Realm&gt;</code> element, as described below, in your
  -    <code>$CATALINA_HOME/conf/server.xml</code> file.</li>
  -<li>Restart Tomcat 4 if it is already running.</li>
  -</ol>
  -
  -<h3>Realm Element Attributes</h3>
  -
  -<p>To configure JDBCRealm, you will create a <code>&lt;Realm&gt;</code>
  -element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file,
  -as described <a href="#Configuring a Realm">above</a>.  The following
  -attributes are supported by this implementation:</p>
  -
  -<attributes>
  -
  -  <attribute name="className" required="true">
  -    <p>The fully qualified Java class name of this Realm implementation.
  -    You <strong>MUST</strong> specify the value
  -    "<code>org.apache.catalina.realm.JDBCRealm</code>" here.</p>
  -  </attribute>
  -
  -  <attribute name="connectionName" required="true">
  -    <p>The database username used to establish a JDBC connection.</p>
  -  </attribute>
  -
  -  <attribute name="connectionPassword" required="true">
  -    <p>The database password used to establish a JDBC connection.</p>
  -  </attribute>
  -
  -  <attribute name="connectionURL" required="true">
  -    <p>The database URL used to establish a JDBC connection.</p>
  -  </attribute>
  -
  -  <attribute name="debug" required="false">
  -    <p>The level of debugging detail logged by this Realm
  -    to the associated <a href="config/logger.html">Logger</a>.  Higher numbers
  -    generate more detailed output.  If not specified, the default
  -    debugging detail level is zero (0).</p>
  -  </attribute>
  -
  -  <attribute name="digest" required="false">
  -    <p>The digest algorithm used to store passwords in non-plaintext formats.
  -    Valid values are those accepted for the algorithm name by the
  -    <code>java.security.MessageDigest</code> class.  See
  -    <a href="#Digested Passwords">Digested Passwords</a> for more
  -    information.  If not specified, passwords are stored in clear text.</p>
  -  </attribute>
  -
  -  <attribute name="driverName" required="true">
  -    <p>The fully qualified Java class name of the JDBC driver to be used.
  -    Consult the documentation for your JDBC driver for the appropriate
  -    value.</p>
  -  </attribute>
  -
  -  <attribute name="roleNameCol" required="true">
  -    <p>The name of the column, in the <em>user roles</em> table, that
  -    contains the name of a role assigned to this user.</p>
  -  </attribute>
  -
  -  <attribute name="userCredCol" required="true">
  -    <p>The name of the column, in the <em>users</em> table, that contains
  -    the password for this user (either in clear text, or digested if the
  -    <code>digest</code> attribute is set).</p>
  -  </attribute>
  -
  -  <attribute name="userNameCol" required="true">
  -    <p>The name of the column, in the <em>users</em> and <em>user roles</em>
  -    tables, that contains the username of this user.</p>
  -  </attribute>
  -
  -  <attribute name="userRoleTable" required="true">
  -    <p>The name of the table that contains one row for each <em>role</em>
  -    assigned to a particular <em>username</em>.  This table must include at
  -    least the columns named by the <code>userNameCol</code> and
  -    <code>roleNameCol</code> attributes.</p>
  -  </attribute>
  -
  -  <attribute name="userTable" required="true">
  -    <p>The name of the table that contains one row for each <em>username</em>
  -    to be recognized by Tomcat.  This table must include at least the columns
  -    named by the <code>userNameCol</code> and <code>userCredCol</code>
  -    attributes.</p>
  -  </attribute>
  -
  -</attributes>
  -
  -<h3>Example</h3>
  -
  -<p>An example SQL script to create the needed tables might look something
  -like this (adapt the syntax as required for your particular database):</p>
  -<source>
  -create table users (
  -  user_name         varchar(15) not null primary key,
  -  user_pass         varchar(15) not null
  -);
  -
  -create table user_roles (
  -  user_name         varchar(15) not null,
  -  role_name         varchar(15) not null,
  -  primary key (user_name, role_name)
  -);
  -</source>
  -
  -<p>Example <code>Realm</code> elements are included (commented out) in the
  -default <code>$CATALINA_HOME/conf/server.xml</code> file.  Here's an example
  -for using a MySQL database called "authority", configured with the tables
  -described above, and accessed with username "dbuser" and password "dbpass":</p>
  -<source>
  -&lt;Realm className="org.apache.catalina.realm.JDBCRealm" debug="99"
  -      driverName="org.gjt.mm.mysql.Driver"
  -   connectionURL="jdbc:mysql://localhost/authority?user=dbuser;password=dbpass"
  -       userTable="users" userNameCol="user_name" userCredCol="user_pass"
  -   userRoleTable="user_roles" roleNameCol="role_name"/&gt;
  -</source>
  -
  -<h3>Additional Notes</h3>
  -
  -<p>JDBCRealm operates according to the following rules:</p>
  -<ul>
  -<li>When a user attempts to access a protected resource for the first time,
  -    Tomcat 4 will call the <code>authenticate()</code> method of this
  -    <code>Realm</code>.  Thus, any changes you have made to the database
  -    directly (new users, changed passwords or roles, etc.) will be immediately
  -    reflected.</li>
  -<li>Once a user has been authenticated, the user (and his or her associated
  -    roles) are cached within Tomcat for the duration of the user's login.
  -    (For FORM-based authentication, that means until the session times out or
  -    is invalidated; for BASIC authentication, that means until the user
  -    closes their browser).  Any changes to the database information for an
  -    already authenticated user will <strong>not</strong> be reflected until
  -    the next time that user logs on again.</li>
  -<li>Administering the information in the <em>users</em> and <em>user roles</em>
  -    table is the responsibility of your own applications.  Tomcat does not
  -    provide any built-in capabilities to maintain users and roles.</li>
  -<li>Debugging and exception messages logged by this <code>Realm</code> will
  -    be recorded by the <code>Logger</code> that is associated with our
  -    surrounding <code>Context</code>, <code>Host</code>, or
  -    <code>Engine</code>.  By default, the corresponding Logger will create a
  -    log file in the <code>$CATALINA_HOME/logs</code> directory.</li>
  -</ul>
  -
  -</subsection>
  -
  -
  -<subsection name="JNDIRealm">
  -
  -<h3>Introduction</h3>
  -
  -<p><strong>JNDIRealm</strong> is an implementation of the Tomcat 4
  -<code>Realm</code> interface that looks up users in a directory server
  -accessed by a JNDI provider (typically, the standard LDAP provider that
  -is available with the JNDI API classes).  There is substantial configuration
  -flexibility that lets you adapt to the existing schema inside your directory
  -server, as long as it conforms to the following requirements:</p>
  -<ul>
  -<li>Each user that can be authenticated is represented by an individual
  -    element in the top level <code>DirContext</code> that is accessed
  -    via the <code>connectionURL</code> attribute.</li>
  -<li>The <em>user</em> element must have the following characteristics:
  -    <ul>
  -    <li>The distinguished name (<code>dn</code>) attribute of this element
  -        contains the username that is presented for authentication.</li>
  -    <li>There must be an attribute (identified by the <code>userPassword</code>
  -        attribute of our <code>Realm</code> element) that contains the user's
  -        password, either in clear text or digested (see below for more info).
  -        </li>
  -    </ul></li>
  -<li>Each group of users that has been assigned a particular role is
  -    represented by an individual element in the top level
  -    <code>DirContext</code> that is accessed via the
  -    <code>connectionURL</code> attribute.</li>
  -<li>The <em>user group</em> element must have the following characteristics:
  -    <ul>
  -    <li>The set of all possible groups of interest can be selected by an LDAP
  -        search pattern configured by the <code>roleSearch</code> attribute
  -        of our <code>Realm</code> element.</li>
  -    <li>The <code>roleSearch</code> pattern optionally includes pattern
  -        replacements "{0}" for the distinguished name, and/or "{1} for the
  -        username, of the authenticated user for which roles will be
  -        retrieved.</li>
  -    <li>The <code>roleBase</code> attribute can be set to the element that
  -        is the base of the search for matching roles.  If not specified,
  -        the entire directory context will be searched.</li>
  -    <li>The <code>roleSubtree</code> attribute can be set to <code>true</code>
  -        if you wish to search the entire subtree of the directory context.
  -        The default value of <code>false</code> requests a search of only the
  -        current level.</li>
  -    <li>The element includes an attribute (whose name is configured by the
  -        <code>roleName</code> attribute of our <code>Realm</code> element)
  -        containing the name of the role represented by this element.</li>
  -    </ul></li>
  -<li>There must be an administrator username and password that Tomcat can
  -    use to establish a connection to the directory server, with at least
  -    read-only access to the information described above.  A future
  -    version of Tomcat will support an option to use the user's username and
  -    password to attempt this connection.</li>
  -</ul>
  -
  -<h3>Quick Start</h3>
  -
  -<p>To set up Tomcat to use JNDIRealm, you will need to follow these steps:</p>
  -<ol>
  -<li>Make sure your directory server is configured with a schema that matches
  -    the requirements listed above.</li>
  -<li>Configure a username and password for use by Tomcat, that has
  -    at least read only access to the information described above.  (Tomcat will
  -    never attempt to modify this information.)</li>
  -<li>Place a copy of the JNDI driver you will be using (typically
  -    <code>ldap.jar</code> available with JNDI) inside the
  -    <code>$CATALINA_HOME/server/lib</code> directory (if you do not need it
  -    visible to web applications) or <code>$CATALINA_HOME/common/lib</code>
  -    (if it will be used both by Tomcat 4 <em>and</em> by your apps).</li>
  -<li>Set up a <code>&lt;Realm&gt;</code> element, as described below, in your
  -    <code>$CATALINA_HOME/conf/server.xml</code> file.</li>
  -<li>Restart Tomcat 4 if it is already running.</li>
  -</ol>
  -
  -<h3>Realm Element Attributes</h3>
  -
  -<p>To configure JNDIRealm, you will create a <code>&lt;Realm&gt;</code>
  -element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file,
  -as described <a href="#Configuring a Realm">above</a>.  The following
  -attributes are supported by this implementation:</p>
  -
  -<attributes>
  -
  -  <attribute name="className" required="true">
  -    <p>The fully qualified Java class name of this Realm implementation.
  -    You <strong>MUST</strong> specify the value
  -    "<code>org.apache.catalina.realm.JDBCRealm</code>" here.</p>
  -  </attribute>
  -
  -  <attribute name="connectionName" required="true">
  -    <p>The directory server username used to establish a JNDI connection.</p>
  -  </attribute>
  -
  -  <attribute name="connectionPassword" required="true">
  -    <p>The directory server password used to establish a JNDI connection.</p>
  -  </attribute>
  -
  -  <attribute name="connectionURL" required="true">
  -    <p>The directory server URL used to establish a JNDI connection.</p>
  -  </attribute>
  -
  -  <attribute name="contextFactory" required="false">
  -    <p>The fully qualified Java class name of the JNDI context factory to be
  -    used for this connection.  By default, the standard JNDI LDAP provider
  -    is used (<code>com.sun.jndi.ldap.LdapCtxFactory</code>).</p>
  -  </attribute>
  -
  -  <attribute name="debug" required="false">
  -    <p>The level of debugging detail logged by this Realm
  -    to the associated <a href="config/logger.html">Logger</a>.  Higher numbers
  -    generate more detailed output.  If not specified, the default
  -    debugging detail level is zero (0).</p>
  -  </attribute>
  -
  -  <attribute name="digest" required="false">
  -    <p>The digest algorithm used to store passwords in non-plaintext formats.
  -    Valid values are those accepted for the algorithm name by the
  -    <code>java.security.MessageDigest</code> class.  See
  -    <a href="#Digested Passwords">Digested Passwords</a> for more
  -    information.  If not specified, passwords are stored in clear text.</p>
  -  </attribute>
  -
  -  <attribute name="roleBase" required="false">
  -    <p>The base element for role searches.  If not specified, the top level
  -    element in the directory context will be used.</p>
  -  </attribute>
  -
  -  <attribute name="roleName" required="true">
  -    <p>The name of the directory server attribute containing the role name.</p>
  -  </attribute>
  -
  -  <attribute name="roleSearch" required="true">
  -    <p>An LDAP search pattern for selecting roles in this Realm, following the
  -    syntax supported by the <code>java.text.MessageFormat</code> class.  Use
  -    <code>{0}</code> to substitute in the distinguished name of the user you
  -    want roles for, and/or <code>{1}</code> to substitute in the username of
  -    the user you want roles for.</p>
  -  </attribute>
  -
  -  <attribute name="roleSubtree" required="false">
  -    <p>Set to <code>true</code> if you want role searches to search subtrees
  -    of the element selected by <code>roleBase</code>.  The default value of
  -    <code>false</code> causes only the top level element to be searched.</p>
  -  </attribute>
  -
  -  <attribute name="userPassword" required="true">
  -    <p>The name of the directory server attribute (in the user element) that
  -    contains the cleartext or digested user password (depending on the setting
  -    of the <code>digest</code> attribute).</p>
  -  </attribute>
  -
  -  <attribute name="userPattern" required="true">
  -    <p>An LDAP search pattern for selecting users in this Realm, following the
  -    syntax supported by the <code>java.text.MessageFormat</code> class.  Use
  -    <code>{0}</code> to substitute in the distinguished name of the user you
  -    want to select.</p>
  -  </attribute>
  -
  -</attributes>
  -
  -<h3>Example</h3>
  -
  -<p>Creation of the appropriate schema in your directory server is beyond the
  -scope of this document, because it is unique to each directory server
  -implementation.  In the examples below, we will assume that you are using a
  -distribution of the OpenLDAP directory server (version 2.0.11 or later), which
  -can be downloaded from
  -<a href="http://www.openldap.org">http://www.openldap.org</a>.  Assume that
  -your <code>slapd.conf</code> file contains the following settings
  -(among others):</p>
  -<source>
  -database ldbm
  -suffix dc="mycompany",dc="com"
  -rootdn "cn=Manager,dc=mycompany,dc=com"
  -rootpw secret
  -</source>
  -
  -<p>These settings help us identify values for the values to be specified for
  -<code>connectionName</code>, and <code>connectionPassword</code>, and we
  -will assume for <code>connectionURL</code> that the directory server runs on
  -the same machine as Tomcat.  See
  -<a href="http://java.sun.com/products/jndi/docs.html">http://java.sun.com/products/jndi/docs.html</a>
  -for more information about configuring and using the JNDI LDAP provider.</p>
  -
  -<p>Next, assume that this directory server has been populated with elements
  -as shown below (in LDIF format), which define the same users and roles
  -as the default <code>$CATALINA_HOME/conf/tomcat-users.xml</code> does for
  -MemoryRealm:</p>
  -<source>
  -# Define a user named 'tomcat'
  -dn: cn=tomcat,dc=mycompany,dc=com
  -cn: tomcat
  -userPassword: tomcat
  -sn: Tomcat User
  -objectClass: person
  -
  -# Define a user named 'role1'
  -dn: cn=role1,dc=mycompany,dc=com
  -cn: role1
  -userPassword: tomcat
  -sn: Role1 User
  -objectClass: person
  -
  -# Define a user named 'both'
  -dn: cn=both,dc=mycompany,dc=com
  -cn: both
  -userPassword: tomcat
  -sn: Both User
  -objectClass: person
  -
  -# Define an entry to base role searches on
  -dn: dc=roles,dc=mycompany,dc=com
  -cn: roles
  -objectClass: person
  -sn: Roles Entry
  -
  -# Define all members of the 'tomcat' role
  -dn: cn=tomcat,dc=roles,dc=mycompany,dc=com
  -cn: tomcat
  -objectClass: groupOfUniqueNames
  -uniqueMember: cn=tomcat,dc=mycompany,dc=com
  -uniqueMember: cn=both,dc=mycompany,dc=com
  -
  -# Define all members of the 'role1' role
  -dn: cn=role1,dc=roles,dc=mycompany,dc=com
  -cn: role1
  -objectClass: groupOfUniqueNames
  -uniqueMember: cn=role1,dc=mycompany,dc=com
  -uniqueMember: cn=both,dc=mycompany,dc=com
  -</source>
  -
  -<p>An example <code>Realm</code> element for the OpenLDAP directory server
  -configured as described above might look like this:</p>
  -<source>
  -&lt;Realm   className="org.apache.catalina.realm.JNDIRealm" debug="99"
  -    connectionName="cn=Manager,dc=mycompany,dc=com"
  -connectionPassword="secret"
  -     connectionURL="ldap://localhost:389"
  -          roleBase="dc=roles,dc=mcclan,dc=net"
  -          roleName="cn"
  -        roleSearch="(uniqueMember={0})"
  -       roleSubtree="false"
  -      userPassword="userPassword"
  -       userPattern="cn={0},dc=mycompany,dc=com"
  -/&gt;
  -</source>
  -
  -<h3>Additional Notes</h3>
  -
  -<p>JNDIRealm operates according to the following rules:</p>
  -<ul>
  -<li>When a user attempts to access a protected resource for the first time,
  -    Tomcat 4 will call the <code>authenticate()</code> method of this
  -    <code>Realm</code>.  Thus, any changes you have made to the database
  -    directly (new users, changed passwords or roles, etc.) will be immediately
  -    reflected.</li>
  -<li>Once a user has been authenticated, the user (and his or her associated
  -    roles) are cached within Tomcat for the duration of the user's login.
  -    (For FORM-based authentication, that means until the session times out or
  -    is invalidated; for BASIC authentication, that means until the user
  -    closes their browser).  Any changes to the database information for an
  -    already authenticated user will <strong>not</strong> be reflected until
  -    the next time that user logs on again.</li>
  -<li>Administering the information in the directory server
  -    is the responsibility of your own applications.  Tomcat does not
  -    provide any built-in capabilities to maintain users and roles.</li>
  -<li>Debugging and exception messages logged by this <code>Realm</code> will
  -    be recorded by the <code>Logger</code> that is associated with our
  -    surrounding <code>Context</code>, <code>Host</code>, or
  -    <code>Engine</code>.  By default, the corresponding Logger will create a
  -    log file in the <code>$CATALINA_HOME/logs</code> directory.</li>
  -</ul>
  -
  -</subsection>
  -
  -
  -<subsection name="MemoryRealm">
  -
  -<h3>Introduction</h3>
  -
  -<p><strong>MemoryRealm</strong> is a simple demonstration implementation of the
  -Tomcat 4 <code>Realm</code> interface.  It is not designed for production use.
  -At startup time, MemoryRealm loads information about all users, and their
  -corresponding roles, from an XML document (by default, this document is loaded from <code>$CATALINA_HOME/conf/tomcat-users.xml</code>).  Changes to the data
  -in this file are not recognized until Tomcat is restarted.</p>
  -
  -<h3>Realm Element Attributes</h3>
  -
  -<p>To configure MemoryRealm, you will create a <code>&lt;Realm&gt;</code>
  -element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file,
  -as described <a href="#Configuring a Realm">above</a>.  The following
  -attributes are supported by this implementation:</p>
  -
  -<attributes>
  -
  -  <attribute name="className" required="true">
  -    <p>The fully qualified Java class name of this Realm implementation.
  -    You <strong>MUST</strong> specify the value
  -    "<code>org.apache.catalina.realm.MemoryRealm</code>" here.</p>
  -  </attribute>
  -
  -  <attribute name="debug" required="false">
  -    <p>The level of debugging detail logged by this Realm
  -    to the associated <a href="config/logger.html">Logger</a>.  Higher numbers
  -    generate more detailed output.  If not specified, the default
  -    debugging detail level is zero (0).</p>
  -  </attribute>
  -
  -  <attribute name="digest" required="false">
  -    <p>The digest algorithm used to store passwords in non-plaintext formats.
  -    Valid values are those accepted for the algorithm name by the
  -    <code>java.security.MessageDigest</code> class.  See
  -    <a href="#Digested Passwords">Digested Passwords</a> for more
  -    information.  If not specified, passwords are stored in clear text.</p>
  -  </attribute>
  -
  -  <attribute name="pathname" required="false">
  -    <p>Absolute or relative (to $CATALINA_HOME) pathname of the XML document
  -    containing our valid usernames, passwords, and roles.  See below for more
  -    information on the format of this file.  If not specified, the value
  -    <code>conf/tomcat-users.xml</code> is used.</p>
  -  </attribute>
  -
  -</attributes>
  -
  -<h3>User File Format</h3>
  -
  -<p>The users file (by default, <code>conf/tomcat-users.xml</code> must be an
  -XML document, with a root element <code>&lt;tomcat-users&gt;</code>.  Nested
  -inside the root element will be a <code>&lt;user&gt;</code> element for each
  -valid user, consisting of the following attributes:</p>
  -<ul>
  -<li><strong>name</strong> - Username this user must log on with.</li>
  -<li><strong>password</strong> - Password this user must log on with (in
  -    clear text if the <code>digest</code> attribute was not set on the
  -    <code>&lt;Realm&gt;</code> element, or digested appropriately as
  -    described <a href="#Digested Passwords">here</a> otherwise).</li>
  -<li><strong>roles</strong> - Comma-delimited list of the role names
  -    associated with this user.</li>
  -</ul>
  -
  -<h3>Example</h3>
  -
  -<p>The default installation of Tomcat 4 is configured with a MemoryRealm
  -nested inside the <code>&lt;Engine&gt;</code> element, so that it applies
  -to all virtual hosts and web applications.  The default contents of the
  -<code>conf/tomcat-users.xml</code> file is:</p>
  -<source>
  -&lt;tomcat-users&gt;
  -  &lt;user name="tomcat" password="tomcat" roles="tomcat" /&gt;
  -  &lt;user name="role1"  password="tomcat" roles="role1"  /&gt;
  -  &lt;user name="both"   password="tomcat" roles="tomcat,role1" /&gt;
  -&lt;/tomcat-users&gt;
  -</source>
  -
  -<h3>Additional Notes</h3>
  -
  -<p>MemoryRealm operates according to the following rules:</p>
  -<ul>
  -<li>When Tomcat first starts up, it loads all defined users and their
  -    associated information from the users file.  Changes to the data in
  -    this file will <strong>not</strong> be recognized until Tomcat is
  -    restarted.</li>
  -<li>When a user attempts to access a protected resource for the first time,
  -    Tomcat 4 will call the <code>authenticate()</code> method of this
  -    <code>Realm</code>.</li>
  -<li>Once a user has been authenticated, the user (and his or her associated
  -    roles) are cached within Tomcat for the duration of the user's login.
  -    (For FORM-based authentication, that means until the session times out or
  -    is invalidated; for BASIC authentication, that means until the user
  -    closes their browser).</li>
  -<li>Administering the information in the users file is the responsibility
  -    of your application.  Tomcat does not
  -    provide any built-in capabilities to maintain users and roles.</li>
  -<li>Debugging and exception messages logged by this <code>Realm</code> will
  -    be recorded by the <code>Logger</code> that is associated with our
  -    surrounding <code>Context</code>, <code>Host</code>, or
  -    <code>Engine</code>.  By default, the corresponding Logger will create a
  -    log file in the <code>$CATALINA_HOME/logs</code> directory.</li>
  -</ul>
  -
  -
  -</subsection>
  -
  -
  -</section>
  -
  -
  -<section name="Common Features">
  -
  -
  -<subsection name="Digested Passwords">
  -
  -<p>For each of the standard <code>Realm</code> implementations, the user's
  -password (by default) is stored in clear text.  In many environments, this is
  -undesireable because casual observers of the authentication data can collect
  -enough information to log on successfully, and impersonate other users.
  -To avoid this problem, the standard implementations support the concept of
  -<em>digesting</em> user passwords.  This causes the stored version of the
  -passwords to be encoded (in a form that is not easily reversible), but that
  -the <code>Realm</code> implementation can still utilize for authentication.</p>
  -
  -<p>Digested passwords are selected by specifying the <code>digest</code>
  -attribute on your <code>&lt;Realm&gt;</code> element.  The value for this
  -attribute must be one of the digest algorithms supported by the
  -<code>java.security.MessageDigest</code> class (SHA, MD2, or MD5).  When you
  -select this option, the contents of the password that is stored in the
  -<code>Realm</code> must be the cleartext version of the password, as digested
  -by the specified algorithm.</p>
  -
  -<p>When the <code>authenticate()</code> method of the Realm is called, the
  -(cleartext) password specified by the user is itself digested by the same
  -algorithm, and the result is compared with the value returned by the
  -<code>Realm</code>.  An equal match implies that the cleartext version of the
  -original password is the same as the one presented by the user, so that this
  -user should be authorized.</p>
  -
  -<p>To calculate the digested value of a cleartext password, two convenience
  -techniques are supported:</p>
  -<ul>
  -<li>If you are writing an application that needs to calculate digested
  -    passowrds dynamically, call the static <code>Digest()</code> method of the
  -    <code>org.apache.catalina.realm.RealmBase</code> class, passing the
  -    cleartext password and the digest algorithm name as arguments.  This
  -    method will return the digested password.</li>
  -<li>If you want to execute a command line utility to calculate the digested
  -    password, simply execute
  -<source>
  -java org.apache.catalina.realm.RealmBase \
  -    -a {algorithm} {cleartext-password}
  -</source>
  -    and the digested version of this cleartext password will be returned to
  -    standard output.</li>
  -</ul>
  -
  -<p>To use either of the above techniques, the
  -<code>$CATALINA_HOME/server/lib/catalina.jar</code> file will need to be
  -on your class path to make the <code>RealmBase</code> class available.</p>
  -
  -</subsection>
  -
  -
  -<subsection name="Example Application">
  -
  -<p>The example application shipped with Tomcat 4 includes an area that is
  -protected by a security constraint, utilizing form-based login.  To access it,
  -point your browser at
  -<a href="http://localhost:8080/examples/jsp/security/protected/">http://localhost:8080/examples/jsp/security/protected/</a>
  -and log on with one of the usernames and passwords described for the default
  -<a href="#MemoryRealm">MemoryRealm</a>.</p>
  -
  -</subsection>
  -
  -
  -<subsection name="Manager Application">
  -
  -<p>If you wish to use the <a href="manager-howto.html">Manager Application</a>
  -to deploy and undeploy applications in a running Tomcat 4 installation, you
  -MUST add the "manager" role to at least one username in your selected Realm
  -implementation.  This is because the manager web application itself uses a
  -security constraint that requires role "manager" to access ANY request URI
  -within that application.</p>
  -
  -<p>For security reasons, no username in the default Realm (i.e. using
  -<code>conf/tomcat-users.xml</code> is assigned the "manager" role.  Therfore,
  -no one will be able to utilize the features of this application until the
  -Tomcat administrator specifically assigns this role to one or more users.</p>
  -
  -</subsection>
  -
  -
  -</section>
  -
  -
  -</body>
  -
  -</document>
  +<?xml version="1.0"?>
  +<!DOCTYPE document [
  +  <!ENTITY project SYSTEM "project.xml">
  +]>
  +<document>
  +
  +    &project;
  +
  +    <properties>
  +        <author email="craigmcc@apache.org">Craig R. McClanahan</author>
  +        <title>Realm Configuration HOW-TO</title>
  +    </properties>
  +
  +<body>
  +
  +
  +<section name="Quick Start">
  +
  +<p>This document describes how to configure Tomcat to support <em>container
  +managed security</em>, by connecting to an existing "database" of usernames,
  +passwords, and user roles.  You only need to care about this if you are using
  +a web application that includes one or more
  +<code>&lt;security-constraint&gt;</code> elements, and a
  +<code>&lt;login-config&gt;</code> element defining how users are required
  +to authenticate themselves.  If you are not utilizing these features, you can
  +safely skip this document.</p>
  +
  +<p>For fundamental background information about container managed security,
  +see the <a href="http://java.sun.com/products/servlet/download.html">Servlet
  +Specification (Version 2.3)</a>, Section 12.  For a more introductory level
  +document for web application developers as well as administrators, see
  +(<strong>FIXME</strong> - link to backgrounder on container managed security
  +to be provided).</p>
  +
  +<p>For information about utilizing the <em>Single Sign On</em> feature of
  +Tomcat 4 (allowing a user to authenticate themselves once across the entire
  +set of web applications associated with a virtual host), see
  +<a href="config/host.html#Single Sign On">here</a>.</p>
  +
  +</section>
  +
  +
  +<section name="Overview">
  +
  +
  +<subsection name="What is a Realm?">
  +
  +<p>A <strong>Realm</strong> is a "database" of usernames and passwords that
  +identify valid users of a web application (or set of web applications), plus
  +an enumeration of the list of <em>roles</em> associated with each valid user.
  +You can think of roles as similar to <em>groups</em> in Unix-like operating
  +systems, because access to specific web application resources is granted to
  +all users possessing a particular role (rather than enumerating the list of
  +associated usernames).  A particular user can have any number of roles
  +associated with their username.</p>
  +
  +<p>Although the Servlet Specification describes a portable mechanism for
  +applications to <em>declare</em> their security requirements (in the
  +<code>web.xml</code> deployment descriptor), there is no portable API
  +defining the interface between a servlet container and the associated user
  +and role information.  In many cases, however, it is desireable to "connect"
  +a servlet container to some existing authentication database or mechanism
  +that already exists in the production environment.  Therefore, Tomcat 4
  +defines a Java interface (<code>org.apache.catalina.Realm</code>) that
  +can be implemented by "plug in" components to establish this connection.
  +Three standard plug-ins are provided, supporting connection to three different
  +sources of authentication information:</p>
  +<ul>
  +<li><a href="#JDBCRealm">JDBCRealm</a> - Accesses authentication information
  +    stored in a relational database, accessed via a JDBC driver.</li>
  +<li><a href="#JNDIRealm">JNDIRealm</a> - Accesses authentication information
  +    stored in an LDAP based directory server, accessed via a JNDI provider.
  +    </li>
  +<li><a href="#MemoryRealm">MemoryRealm</a> - Accesses authentication
  +    information stored in an in-memory object collection, which is initialized
  +    from an XML document (<code>conf/tomcat-users.xml</code>).</li>
  +</ul>
  +
  +<p>It is also possible to write your own <code>Realm</code> implementation,
  +and integrate it with Tomcat 4.  However, doing this is beyond the scope of
  +this document.  See (<strong>FIXME</strong> - reference to developer stuff)
  +for more information.</p>
  +
  +</subsection>
  +
  +
  +<subsection name="Configuring a Realm">
  +
  +<p>Before getting into the details of the standard Realm implementations, it is
  +important to understand, in general terms, how a Realm is configured.  In
  +general, you will be adding an XML element to your <code>conf/server.xml</code>
  +configuration file, that looks something like this:</p>
  +
  +<source>
  +&lt;Realm className="... class name for this implementation"
  +       ... other attributes for this implementation .../&gt;
  +</source>
  +
  +<p>The <code>&lt;Realm&gt;</code> element can be nested inside one of three
  +different elements, which has a direct impact on the "scope" of that Realm
  +(i.e. which web applications will share the same authentication information):
  +</p>
  +<ul>
  +<li><em>Inside an &lt;Engine&gt; element</em> - This Realm will be shared
  +    across ALL web applications on ALL virtual hosts, UNLESS it is overridden
  +    by a Realm element nested inside a subordinate <code>&lt;Host&gt;</code>
  +    or <code>&lt;Context&gt;</code> element.</li>
  +<li><em>Inside a &lt;Host&gt; element</em> - This Realm will be shared across
  +    ALL web applications for THIS virtual host, UNLESS it is overridden
  +    by a Realm element nested inside a subordinate <code>&lt;Context&gt;</code>
  +    element.</li>
  +<li><em>Inside a &lt;Context&gt; element</em> - This Realm will be used ONLY
  +    for THIS web application.</li>
  +</ul>
  +
  +
  +</subsection>
  +
  +
  +</section>
  +
  +
  +<section name="Standard Realm Implementations">
  +
  +
  +<subsection name="JDBCRealm">
  +
  +<h3>Introduction</h3>
  +
  +<p><strong>JDBCRealm</strong> is an implementation of the Tomcat 4
  +<code>Realm</code> interface that looks up users in a relational database
  +accessed via a JDBC driver.  There is substantial configuration flexibility
  +that lets you adapt to existing table and column names, as long as your
  +database structure conforms to the following requirements:</p>
  +<ul>
  +<li>There must be a table, referenced below as the <em>users</em> table,
  +    that contains one row for every valid user that this <code>Realm</code>
  +    should recognize.</li>
  +<li>The <em>users</em> table must contain at least two columns (it may
  +    contain more if your existing applications required it):
  +    <ul>
  +    <li>Username to be recognized by Tomcat when the user logs in.</li>
  +    <li>Password to be recognized by Tomcat when the user logs in.
  +        This value may in cleartext or digested - see below for more
  +        information.</li>
  +    </ul></li>
  +<li>There must be a table, referenced below as the <em>user roles</em> table,
  +    that contains one row for every valid role that is assigned to a
  +    particular user.  It is legal for a user to have zero, one, or more than
  +    one valid role.</li>
  +<li>The <em>user roles</em> table must contain at least two columns (it may
  +    contain more if your existing applications required it):
  +    <ul>
  +    <li>Username to be recognized by Tomcat (same value as is specified
  +        in the <em>users</em> table).</li>
  +    <li>Role name of a valid role associated with this user.</li>
  +    </ul></li>
  +</ul>
  +
  +<h3>Quick Start</h3>
  +
  +<p>To set up Tomcat to use JDBCRealm, you will need to follow these steps:</p>
  +<ol>
  +<li>If you have not yet done so, create tables and columns in your database
  +    that conform to the requirements described above.</li>
  +<li>Configure a database username and password for use by Tomcat, that has
  +    at least read only access to the tables described above.  (Tomcat will
  +    never attempt to write to these tables.)</li>
  +<li>Place a copy of the JDBC driver you will be using inside the
  +    <code>$CATALINA_HOME/server/lib</code> directory (if you do not need it
  +    visible to web applications) or <code>$CATALINA_HOME/common/lib</code>
  +    (if it will be used both by Tomcat 4 <em>and</em> by your apps).
  +    Note that <strong>only</strong> JAR files are recognized!</li>
  +<li>Set up a <code>&lt;Realm&gt;</code> element, as described below, in your
  +    <code>$CATALINA_HOME/conf/server.xml</code> file.</li>
  +<li>Restart Tomcat 4 if it is already running.</li>
  +</ol>
  +
  +<h3>Realm Element Attributes</h3>
  +
  +<p>To configure JDBCRealm, you will create a <code>&lt;Realm&gt;</code>
  +element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file,
  +as described <a href="#Configuring a Realm">above</a>.  The following
  +attributes are supported by this implementation:</p>
  +
  +<attributes>
  +
  +  <attribute name="className" required="true">
  +    <p>The fully qualified Java class name of this Realm implementation.
  +    You <strong>MUST</strong> specify the value
  +    "<code>org.apache.catalina.realm.JDBCRealm</code>" here.</p>
  +  </attribute>
  +
  +  <attribute name="connectionName" required="true">
  +    <p>The database username used to establish a JDBC connection.</p>
  +  </attribute>
  +
  +  <attribute name="connectionPassword" required="true">
  +    <p>The database password used to establish a JDBC connection.</p>
  +  </attribute>
  +
  +  <attribute name="connectionURL" required="true">
  +    <p>The database URL used to establish a JDBC connection.</p>
  +  </attribute>
  +
  +  <attribute name="debug" required="false">
  +    <p>The level of debugging detail logged by this Realm
  +    to the associated <a href="config/logger.html">Logger</a>.  Higher numbers
  +    generate more detailed output.  If not specified, the default
  +    debugging detail level is zero (0).</p>
  +  </attribute>
  +
  +  <attribute name="digest" required="false">
  +    <p>The digest algorithm used to store passwords in non-plaintext formats.
  +    Valid values are those accepted for the algorithm name by the
  +    <code>java.security.MessageDigest</code> class.  See
  +    <a href="#Digested Passwords">Digested Passwords</a> for more
  +    information.  If not specified, passwords are stored in clear text.</p>
  +  </attribute>
  +
  +  <attribute name="driverName" required="true">
  +    <p>The fully qualified Java class name of the JDBC driver to be used.
  +    Consult the documentation for your JDBC driver for the appropriate
  +    value.</p>
  +  </attribute>
  +
  +  <attribute name="roleNameCol" required="true">
  +    <p>The name of the column, in the <em>user roles</em> table, that
  +    contains the name of a role assigned to this user.</p>
  +  </attribute>
  +
  +  <attribute name="userCredCol" required="true">
  +    <p>The name of the column, in the <em>users</em> table, that contains
  +    the password for this user (either in clear text, or digested if the
  +    <code>digest</code> attribute is set).</p>
  +  </attribute>
  +
  +  <attribute name="userNameCol" required="true">
  +    <p>The name of the column, in the <em>users</em> and <em>user roles</em>
  +    tables, that contains the username of this user.</p>
  +  </attribute>
  +
  +  <attribute name="userRoleTable" required="true">
  +    <p>The name of the table that contains one row for each <em>role</em>
  +    assigned to a particular <em>username</em>.  This table must include at
  +    least the columns named by the <code>userNameCol</code> and
  +    <code>roleNameCol</code> attributes.</p>
  +  </attribute>
  +
  +  <attribute name="userTable" required="true">
  +    <p>The name of the table that contains one row for each <em>username</em>
  +    to be recognized by Tomcat.  This table must include at least the columns
  +    named by the <code>userNameCol</code> and <code>userCredCol</code>
  +    attributes.</p>
  +  </attribute>
  +
  +</attributes>
  +
  +<h3>Example</h3>
  +
  +<p>An example SQL script to create the needed tables might look something
  +like this (adapt the syntax as required for your particular database):</p>
  +<source>
  +create table users (
  +  user_name         varchar(15) not null primary key,
  +  user_pass         varchar(15) not null
  +);
  +
  +create table user_roles (
  +  user_name         varchar(15) not null,
  +  role_name         varchar(15) not null,
  +  primary key (user_name, role_name)
  +);
  +</source>
  +
  +<p>Example <code>Realm</code> elements are included (commented out) in the
  +default <code>$CATALINA_HOME/conf/server.xml</code> file.  Here's an example
  +for using a MySQL database called "authority", configured with the tables
  +described above, and accessed with username "dbuser" and password "dbpass":</p>
  +<source>
  +&lt;Realm className="org.apache.catalina.realm.JDBCRealm" debug="99"
  +      driverName="org.gjt.mm.mysql.Driver"
  +   connectionURL="jdbc:mysql://localhost/authority?user=dbuser;password=dbpass"
  +       userTable="users" userNameCol="user_name" userCredCol="user_pass"
  +   userRoleTable="user_roles" roleNameCol="role_name"/&gt;
  +</source>
  +
  +<h3>Additional Notes</h3>
  +
  +<p>JDBCRealm operates according to the following rules:</p>
  +<ul>
  +<li>When a user attempts to access a protected resource for the first time,
  +    Tomcat 4 will call the <code>authenticate()</code> method of this
  +    <code>Realm</code>.  Thus, any changes you have made to the database
  +    directly (new users, changed passwords or roles, etc.) will be immediately
  +    reflected.</li>
  +<li>Once a user has been authenticated, the user (and his or her associated
  +    roles) are cached within Tomcat for the duration of the user's login.
  +    (For FORM-based authentication, that means until the session times out or
  +    is invalidated; for BASIC authentication, that means until the user
  +    closes their browser).  Any changes to the database information for an
  +    already authenticated user will <strong>not</strong> be reflected until
  +    the next time that user logs on again.</li>
  +<li>Administering the information in the <em>users</em> and <em>user roles</em>
  +    table is the responsibility of your own applications.  Tomcat does not
  +    provide any built-in capabilities to maintain users and roles.</li>
  +<li>Debugging and exception messages logged by this <code>Realm</code> will
  +    be recorded by the <code>Logger</code> that is associated with our
  +    surrounding <code>Context</code>, <code>Host</code>, or
  +    <code>Engine</code>.  By default, the corresponding Logger will create a
  +    log file in the <code>$CATALINA_HOME/logs</code> directory.</li>
  +</ul>
  +
  +</subsection>
  +
  +
  +<subsection name="JNDIRealm">
  +
  +<h3>Introduction</h3>
  +
  +<p><strong>JNDIRealm</strong> is an implementation of the Tomcat 4
  +<code>Realm</code> interface that looks up users in a directory server
  +accessed by a JNDI provider (typically, the standard LDAP provider that
  +is available with the JNDI API classes).  There is substantial configuration
  +flexibility that lets you adapt to the existing schema inside your directory
  +server, as long as it conforms to the following requirements:</p>
  +<ul>
  +<li>Each user that can be authenticated is represented by an individual
  +    element in the top level <code>DirContext</code> that is accessed
  +    via the <code>connectionURL</code> attribute.</li>
  +<li>The <em>user</em> element must have the following characteristics:
  +    <ul>
  +    <li>The distinguished name (<code>dn</code>) attribute of this element
  +        contains the username that is presented for authentication.</li>
  +    <li>There must be an attribute (identified by the <code>userPassword</code>
  +        attribute of our <code>Realm</code> element) that contains the user's
  +        password, either in clear text or digested (see below for more info).
  +        </li>
  +    </ul></li>
  +<li>Each group of users that has been assigned a particular role is
  +    represented by an individual element in the top level
  +    <code>DirContext</code> that is accessed via the
  +    <code>connectionURL</code> attribute.</li>
  +<li>The <em>user group</em> element must have the following characteristics:
  +    <ul>
  +    <li>The set of all possible groups of interest can be selected by an LDAP
  +        search pattern configured by the <code>roleSearch</code> attribute
  +        of our <code>Realm</code> element.</li>
  +    <li>The <code>roleSearch</code> pattern optionally includes pattern
  +        replacements "{0}" for the distinguished name, and/or "{1} for the
  +        username, of the authenticated user for which roles will be
  +        retrieved.</li>
  +    <li>The <code>roleBase</code> attribute can be set to the element that
  +        is the base of the search for matching roles.  If not specified,
  +        the entire directory context will be searched.</li>
  +    <li>The <code>roleSubtree</code> attribute can be set to <code>true</code>
  +        if you wish to search the entire subtree of the directory context.
  +        The default value of <code>false</code> requests a search of only the
  +        current level.</li>
  +    <li>The element includes an attribute (whose name is configured by the
  +        <code>roleName</code> attribute of our <code>Realm</code> element)
  +        containing the name of the role represented by this element.</li>
  +    </ul></li>
  +<li>There must be an administrator username and password that Tomcat can
  +    use to establish a connection to the directory server, with at least
  +    read-only access to the information described above.  A future
  +    version of Tomcat will support an option to use the user's username and
  +    password to attempt this connection.</li>
  +</ul>
  +
  +<h3>Quick Start</h3>
  +
  +<p>To set up Tomcat to use JNDIRealm, you will need to follow these steps:</p>
  +<ol>
  +<li>Make sure your directory server is configured with a schema that matches
  +    the requirements listed above.</li>
  +<li>Configure a username and password for use by Tomcat, that has
  +    at least read only access to the information described above.  (Tomcat will
  +    never attempt to modify this information.)</li>
  +<li>Place a copy of the JNDI driver you will be using (typically
  +    <code>ldap.jar</code> available with JNDI) inside the
  +    <code>$CATALINA_HOME/server/lib</code> directory (if you do not need it
  +    visible to web applications) or <code>$CATALINA_HOME/common/lib</code>
  +    (if it will be used both by Tomcat 4 <em>and</em> by your apps).</li>
  +<li>Set up a <code>&lt;Realm&gt;</code> element, as described below, in your
  +    <code>$CATALINA_HOME/conf/server.xml</code> file.</li>
  +<li>Restart Tomcat 4 if it is already running.</li>
  +</ol>
  +
  +<h3>Realm Element Attributes</h3>
  +
  +<p>To configure JNDIRealm, you will create a <code>&lt;Realm&gt;</code>
  +element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file,
  +as described <a href="#Configuring a Realm">above</a>.  The following
  +attributes are supported by this implementation:</p>
  +
  +<attributes>
  +
  +  <attribute name="className" required="true">
  +    <p>The fully qualified Java class name of this Realm implementation.
  +    You <strong>MUST</strong> specify the value
  +    "<code>org.apache.catalina.realm.JDBCRealm</code>" here.</p>
  +  </attribute>
  +
  +  <attribute name="connectionName" required="true">
  +    <p>The directory server username used to establish a JNDI connection.</p>
  +  </attribute>
  +
  +  <attribute name="connectionPassword" required="true">
  +    <p>The directory server password used to establish a JNDI connection.</p>
  +  </attribute>
  +
  +  <attribute name="connectionURL" required="true">
  +    <p>The directory server URL used to establish a JNDI connection.</p>
  +  </attribute>
  +
  +  <attribute name="contextFactory" required="false">
  +    <p>The fully qualified Java class name of the JNDI context factory to be
  +    used for this connection.  By default, the standard JNDI LDAP provider
  +    is used (<code>com.sun.jndi.ldap.LdapCtxFactory</code>).</p>
  +  </attribute>
  +
  +  <attribute name="debug" required="false">
  +    <p>The level of debugging detail logged by this Realm
  +    to the associated <a href="config/logger.html">Logger</a>.  Higher numbers
  +    generate more detailed output.  If not specified, the default
  +    debugging detail level is zero (0).</p>
  +  </attribute>
  +
  +  <attribute name="digest" required="false">
  +    <p>The digest algorithm used to store passwords in non-plaintext formats.
  +    Valid values are those accepted for the algorithm name by the
  +    <code>java.security.MessageDigest</code> class.  See
  +    <a href="#Digested Passwords">Digested Passwords</a> for more
  +    information.  If not specified, passwords are stored in clear text.</p>
  +  </attribute>
  +
  +  <attribute name="roleBase" required="false">
  +    <p>The base element for role searches.  If not specified, the top level
  +    element in the directory context will be used.</p>
  +  </attribute>
  +
  +  <attribute name="roleName" required="true">
  +    <p>The name of the directory server attribute containing the role name.</p>
  +  </attribute>
  +
  +  <attribute name="roleSearch" required="true">
  +    <p>An LDAP search pattern for selecting roles in this Realm, following the
  +    syntax supported by the <code>java.text.MessageFormat</code> class.  Use
  +    <code>{0}</code> to substitute in the distinguished name of the user you
  +    want roles for, and/or <code>{1}</code> to substitute in the username of
  +    the user you want roles for.</p>
  +  </attribute>
  +
  +  <attribute name="roleSubtree" required="false">
  +    <p>Set to <code>true</code> if you want role searches to search subtrees
  +    of the element selected by <code>roleBase</code>.  The default value of
  +    <code>false</code> causes only the top level element to be searched.</p>
  +  </attribute>
  +
  +  <attribute name="userPassword" required="true">
  +    <p>The name of the directory server attribute (in the user element) that
  +    contains the cleartext or digested user password (depending on the setting
  +    of the <code>digest</code> attribute).</p>
  +  </attribute>
  +
  +  <attribute name="userPattern" required="true">
  +    <p>An LDAP search pattern for selecting users in this Realm, following the
  +    syntax supported by the <code>java.text.MessageFormat</code> class.  Use
  +    <code>{0}</code> to substitute in the distinguished name of the user you
  +    want to select.</p>
  +  </attribute>
  +
  +</attributes>
  +
  +<h3>Example</h3>
  +
  +<p>Creation of the appropriate schema in your directory server is beyond the
  +scope of this document, because it is unique to each directory server
  +implementation.  In the examples below, we will assume that you are using a
  +distribution of the OpenLDAP directory server (version 2.0.11 or later), which
  +can be downloaded from
  +<a href="http://www.openldap.org">http://www.openldap.org</a>.  Assume that
  +your <code>slapd.conf</code> file contains the following settings
  +(among others):</p>
  +<source>
  +database ldbm
  +suffix dc="mycompany",dc="com"
  +rootdn "cn=Manager,dc=mycompany,dc=com"
  +rootpw secret
  +</source>
  +
  +<p>These settings help us identify values for the values to be specified for
  +<code>connectionName</code>, and <code>connectionPassword</code>, and we
  +will assume for <code>connectionURL</code> that the directory server runs on
  +the same machine as Tomcat.  See
  +<a href="http://java.sun.com/products/jndi/docs.html">http://java.sun.com/products/jndi/docs.html</a>
  +for more information about configuring and using the JNDI LDAP provider.</p>
  +
  +<p>Next, assume that this directory server has been populated with elements
  +as shown below (in LDIF format), which define the same users and roles
  +as the default <code>$CATALINA_HOME/conf/tomcat-users.xml</code> does for
  +MemoryRealm:</p>
  +<source>
  +# Define a user named 'tomcat'
  +dn: cn=tomcat,dc=mycompany,dc=com
  +cn: tomcat
  +userPassword: tomcat
  +sn: Tomcat User
  +objectClass: person
  +
  +# Define a user named 'role1'
  +dn: cn=role1,dc=mycompany,dc=com
  +cn: role1
  +userPassword: tomcat
  +sn: Role1 User
  +objectClass: person
  +
  +# Define a user named 'both'
  +dn: cn=both,dc=mycompany,dc=com
  +cn: both
  +userPassword: tomcat
  +sn: Both User
  +objectClass: person
  +
  +# Define an entry to base role searches on
  +dn: dc=roles,dc=mycompany,dc=com
  +cn: roles
  +objectClass: person
  +sn: Roles Entry
  +
  +# Define all members of the 'tomcat' role
  +dn: cn=tomcat,dc=roles,dc=mycompany,dc=com
  +cn: tomcat
  +objectClass: groupOfUniqueNames
  +uniqueMember: cn=tomcat,dc=mycompany,dc=com
  +uniqueMember: cn=both,dc=mycompany,dc=com
  +
  +# Define all members of the 'role1' role
  +dn: cn=role1,dc=roles,dc=mycompany,dc=com
  +cn: role1
  +objectClass: groupOfUniqueNames
  +uniqueMember: cn=role1,dc=mycompany,dc=com
  +uniqueMember: cn=both,dc=mycompany,dc=com
  +</source>
  +
  +<p>An example <code>Realm</code> element for the OpenLDAP directory server
  +configured as described above might look like this:</p>
  +<source>
  +&lt;Realm   className="org.apache.catalina.realm.JNDIRealm" debug="99"
  +    connectionName="cn=Manager,dc=mycompany,dc=com"
  +connectionPassword="secret"
  +     connectionURL="ldap://localhost:389"
  +          roleBase="dc=roles,dc=mcclan,dc=net"
  +          roleName="cn"
  +        roleSearch="(uniqueMember={0})"
  +       roleSubtree="false"
  +      userPassword="userPassword"
  +       userPattern="cn={0},dc=mycompany,dc=com"
  +/&gt;
  +</source>
  +
  +<h3>Additional Notes</h3>
  +
  +<p>JNDIRealm operates according to the following rules:</p>
  +<ul>
  +<li>When a user attempts to access a protected resource for the first time,
  +    Tomcat 4 will call the <code>authenticate()</code> method of this
  +    <code>Realm</code>.  Thus, any changes you have made to the database
  +    directly (new users, changed passwords or roles, etc.) will be immediately
  +    reflected.</li>
  +<li>Once a user has been authenticated, the user (and his or her associated
  +    roles) are cached within Tomcat for the duration of the user's login.
  +    (For FORM-based authentication, that means until the session times out or
  +    is invalidated; for BASIC authentication, that means until the user
  +    closes their browser).  Any changes to the database information for an
  +    already authenticated user will <strong>not</strong> be reflected until
  +    the next time that user logs on again.</li>
  +<li>Administering the information in the directory server
  +    is the responsibility of your own applications.  Tomcat does not
  +    provide any built-in capabilities to maintain users and roles.</li>
  +<li>Debugging and exception messages logged by this <code>Realm</code> will
  +    be recorded by the <code>Logger</code> that is associated with our
  +    surrounding <code>Context</code>, <code>Host</code>, or
  +    <code>Engine</code>.  By default, the corresponding Logger will create a
  +    log file in the <code>$CATALINA_HOME/logs</code> directory.</li>
  +</ul>
  +
  +</subsection>
  +
  +
  +<subsection name="MemoryRealm">
  +
  +<h3>Introduction</h3>
  +
  +<p><strong>MemoryRealm</strong> is a simple demonstration implementation of the
  +Tomcat 4 <code>Realm</code> interface.  It is not designed for production use.
  +At startup time, MemoryRealm loads information about all users, and their
  +corresponding roles, from an XML document (by default, this document is loaded from <code>$CATALINA_HOME/conf/tomcat-users.xml</code>).  Changes to the data
  +in this file are not recognized until Tomcat is restarted.</p>
  +
  +<h3>Realm Element Attributes</h3>
  +
  +<p>To configure MemoryRealm, you will create a <code>&lt;Realm&gt;</code>
  +element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file,
  +as described <a href="#Configuring a Realm">above</a>.  The following
  +attributes are supported by this implementation:</p>
  +
  +<attributes>
  +
  +  <attribute name="className" required="true">
  +    <p>The fully qualified Java class name of this Realm implementation.
  +    You <strong>MUST</strong> specify the value
  +    "<code>org.apache.catalina.realm.MemoryRealm</code>" here.</p>
  +  </attribute>
  +
  +  <attribute name="debug" required="false">
  +    <p>The level of debugging detail logged by this Realm
  +    to the associated <a href="config/logger.html">Logger</a>.  Higher numbers
  +    generate more detailed output.  If not specified, the default
  +    debugging detail level is zero (0).</p>
  +  </attribute>
  +
  +  <attribute name="digest" required="false">
  +    <p>The digest algorithm used to store passwords in non-plaintext formats.
  +    Valid values are those accepted for the algorithm name by the
  +    <code>java.security.MessageDigest</code> class.  See
  +    <a href="#Digested Passwords">Digested Passwords</a> for more
  +    information.  If not specified, passwords are stored in clear text.</p>
  +  </attribute>
  +
  +  <attribute name="pathname" required="false">
  +    <p>Absolute or relative (to $CATALINA_HOME) pathname of the XML document
  +    containing our valid usernames, passwords, and roles.  See below for more
  +    information on the format of this file.  If not specified, the value
  +    <code>conf/tomcat-users.xml</code> is used.</p>
  +  </attribute>
  +
  +</attributes>
  +
  +<h3>User File Format</h3>
  +
  +<p>The users file (by default, <code>conf/tomcat-users.xml</code> must be an
  +XML document, with a root element <code>&lt;tomcat-users&gt;</code>.  Nested
  +inside the root element will be a <code>&lt;user&gt;</code> element for each
  +valid user, consisting of the following attributes:</p>
  +<ul>
  +<li><strong>name</strong> - Username this user must log on with.</li>
  +<li><strong>password</strong> - Password this user must log on with (in
  +    clear text if the <code>digest</code> attribute was not set on the
  +    <code>&lt;Realm&gt;</code> element, or digested appropriately as
  +    described <a href="#Digested Passwords">here</a> otherwise).</li>
  +<li><strong>roles</strong> - Comma-delimited list of the role names
  +    associated with this user.</li>
  +</ul>
  +
  +<h3>Example</h3>
  +
  +<p>The default installation of Tomcat 4 is configured with a MemoryRealm
  +nested inside the <code>&lt;Engine&gt;</code> element, so that it applies
  +to all virtual hosts and web applications.  The default contents of the
  +<code>conf/tomcat-users.xml</code> file is:</p>
  +<source>
  +&lt;tomcat-users&gt;
  +  &lt;user name="tomcat" password="tomcat" roles="tomcat" /&gt;
  +  &lt;user name="role1"  password="tomcat" roles="role1"  /&gt;
  +  &lt;user name="both"   password="tomcat" roles="tomcat,role1" /&gt;
  +&lt;/tomcat-users&gt;
  +</source>
  +
  +<h3>Additional Notes</h3>
  +
  +<p>MemoryRealm operates according to the following rules:</p>
  +<ul>
  +<li>When Tomcat first starts up, it loads all defined users and their
  +    associated information from the users file.  Changes to the data in
  +    this file will <strong>not</strong> be recognized until Tomcat is
  +    restarted.</li>
  +<li>When a user attempts to access a protected resource for the first time,
  +    Tomcat 4 will call the <code>authenticate()</code> method of this
  +    <code>Realm</code>.</li>
  +<li>Once a user has been authenticated, the user (and his or her associated
  +    roles) are cached within Tomcat for the duration of the user's login.
  +    (For FORM-based authentication, that means until the session times out or
  +    is invalidated; for BASIC authentication, that means until the user
  +    closes their browser).</li>
  +<li>Administering the information in the users file is the responsibility
  +    of your application.  Tomcat does not
  +    provide any built-in capabilities to maintain users and roles.</li>
  +<li>Debugging and exception messages logged by this <code>Realm</code> will
  +    be recorded by the <code>Logger</code> that is associated with our
  +    surrounding <code>Context</code>, <code>Host</code>, or
  +    <code>Engine</code>.  By default, the corresponding Logger will create a
  +    log file in the <code>$CATALINA_HOME/logs</code> directory.</li>
  +</ul>
  +
  +
  +</subsection>
  +
  +
  +</section>
  +
  +
  +<section name="Common Features">
  +
  +
  +<subsection name="Digested Passwords">
  +
  +<p>For each of the standard <code>Realm</code> implementations, the user's
  +password (by default) is stored in clear text.  In many environments, this is
  +undesireable because casual observers of the authentication data can collect
  +enough information to log on successfully, and impersonate other users.
  +To avoid this problem, the standard implementations support the concept of
  +<em>digesting</em> user passwords.  This causes the stored version of the
  +passwords to be encoded (in a form that is not easily reversible), but that
  +the <code>Realm</code> implementation can still utilize for authentication.</p>
  +
  +<p>Digested passwords are selected by specifying the <code>digest</code>
  +attribute on your <code>&lt;Realm&gt;</code> element.  The value for this
  +attribute must be one of the digest algorithms supported by the
  +<code>java.security.MessageDigest</code> class (SHA, MD2, or MD5).  When you
  +select this option, the contents of the password that is stored in the
  +<code>Realm</code> must be the cleartext version of the password, as digested
  +by the specified algorithm.</p>
  +
  +<p>When the <code>authenticate()</code> method of the Realm is called, the
  +(cleartext) password specified by the user is itself digested by the same
  +algorithm, and the result is compared with the value returned by the
  +<code>Realm</code>.  An equal match implies that the cleartext version of the
  +original password is the same as the one presented by the user, so that this
  +user should be authorized.</p>
  +
  +<p>To calculate the digested value of a cleartext password, two convenience
  +techniques are supported:</p>
  +<ul>
  +<li>If you are writing an application that needs to calculate digested
  +    passowrds dynamically, call the static <code>Digest()</code> method of the
  +    <code>org.apache.catalina.realm.RealmBase</code> class, passing the
  +    cleartext password and the digest algorithm name as arguments.  This
  +    method will return the digested password.</li>
  +<li>If you want to execute a command line utility to calculate the digested
  +    password, simply execute
  +<source>
  +java org.apache.catalina.realm.RealmBase \
  +    -a {algorithm} {cleartext-password}
  +</source>
  +    and the digested version of this cleartext password will be returned to
  +    standard output.</li>
  +</ul>
  +
  +<p>To use either of the above techniques, the
  +<code>$CATALINA_HOME/server/lib/catalina.jar</code> file will need to be
  +on your class path to make the <code>RealmBase</code> class available.</p>
  +
  +</subsection>
  +
  +
  +<subsection name="Example Application">
  +
  +<p>The example application shipped with Tomcat 4 includes an area that is
  +protected by a security constraint, utilizing form-based login.  To access it,
  +point your browser at
  +<a href="http://localhost:8080/examples/jsp/security/protected/">http://localhost:8080/examples/jsp/security/protected/</a>
  +and log on with one of the usernames and passwords described for the default
  +<a href="#MemoryRealm">MemoryRealm</a>.</p>
  +
  +</subsection>
  +
  +
  +<subsection name="Manager Application">
  +
  +<p>If you wish to use the <a href="manager-howto.html">Manager Application</a>
  +to deploy and undeploy applications in a running Tomcat 4 installation, you
  +MUST add the "manager" role to at least one username in your selected Realm
  +implementation.  This is because the manager web application itself uses a
  +security constraint that requires role "manager" to access ANY request URI
  +within that application.</p>
  +
  +<p>For security reasons, no username in the default Realm (i.e. using
  +<code>conf/tomcat-users.xml</code> is assigned the "manager" role.  Therfore,
  +no one will be able to utilize the features of this application until the
  +Tomcat administrator specifically assigns this role to one or more users.</p>
  +
  +</subsection>
  +
  +
  +</section>
  +
  +
  +</body>
  +
  +</document>
  
  
  
  1.10      +420 -420  jakarta-tomcat-4.0/webapps/tomcat-docs/ssl-howto.xml
  
  Index: ssl-howto.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/ssl-howto.xml,v
  retrieving revision 1.9
  retrieving revision 1.10
  diff -u -r1.9 -r1.10
  --- ssl-howto.xml	2001/09/25 04:55:23	1.9
  +++ ssl-howto.xml	2001/11/12 21:03:49	1.10
  @@ -1,420 +1,420 @@
  -<?xml version="1.0"?>
  -<!DOCTYPE document [
  -  <!ENTITY project SYSTEM "project.xml">
  -]>
  -<document>
  -
  -    &project;
  -
  -    <properties>
  -        <author email="ccain@apache.org">Christopher Cain</author>
  -        <title>SSL Configuration HOW-TO</title>
  -    </properties>
  -
  -<body>
  -
  -
  -<section name="Quick-Start Version">
  -
  -    <blockquote><em>
  -    <p>The description below uses the variable name $CATALINA_HOME
  -    to refer to the directory into which you have installed Tomcat 4,
  -    and is the base directory against which most relative paths are
  -    resolved.  However, if you have configured Tomcat 4 for multiple
  -    instances by setting a CATALINA_BASE directory, you should use
  -    $CATALINA_BASE instead of $CATALINA_HOME for each of these
  -    references.</p>
  -    </em></blockquote>
  -
  -<p>To install and configure SSL support on Tomcat 4, you need to follow
  -these simple steps.  For more information, read the rest of this HOW-TO.</p>
  -<ol>
  -<li>Download JSSE 1.0.2 (or later) from
  -   <a href="http://java.sun.com/products/jsse/">http://java.sun.com/products/jsse/</a>
  -   and either make it an <em>installed extension</em> on the system, or else
  -   set an environment variable <code>JSSE_HOME</code> that points at the
  -   directory into which you installed JSSE.</li><br/><br/>
  -<li>Create a certificate keystore by executing the following command:
  -<p>Windows:</p>
  -<source>
  -%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA
  -</source>
  -<p>Unix:</p>
  -<source>
  -$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA
  -</source>
  -<p></p>
  -    and specify a password value of "changeit".</li><br/><br/>
  -<li>Uncomment the "SSL HTTP/1.1 Connector" entry in
  -    <code>$CATALINA_HOME/conf/server.xml</code> and tweak as necessary.</li>
  -    <br/><br/>
  -</ol>
  -
  -
  -</section>
  -
  -
  -<section name="Introduction to SSL">
  -
  -<p>SSL, or Secure Socket Layer, is a technology which allows web browsers and
  -web servers to communicate over a secured connection.  This means that the data
  -being sent is encrypted by one side, transmitted, then decrypted by the other
  -side before processing.  This is a two-way process, meaning that both the
  -server AND the browser encrypt all traffic before sending out data.</p>
  -
  -<p>Another important aspect of the SSL protocol is Authentication.  This means
  -that during your initial attempt to communicate with a web server over a secure
  -connection, that server will present your web browser with a set of
  -credentials, in the form of a "Certificate", as proof the site is who and what
  -it claims to be.  In certain cases, the server may also request a Certificate
  -from your web browser, asking for proof that <em>you</em> are who you claim
  -to be.  This is known as "Client Authentication," although in practice this is
  -used more for business-to-business (B2B) transactions than with individual
  -users.  Most SSL-enabled web servers do not request Client Authentication.</p>
  -
  -</section>
  -
  -<section name="SSL and Tomcat">
  -
  -<p>It is important to note that configuring Tomcat to take advantage of
  -secure sockets is usually only necessary when running it as a stand-alone
  -web server.  When running Tomcat primarily as a Servlet/JSP container behind
  -another web server, such as Apache or Microsoft IIS, it is usually necessary
  -to configure the primary web server to handle the SSL connections from users.
  -Typically, this server will negotiate all SSL-related functionality, then
  -pass on any requests destined for the Tomcat container only after decrypting
  -those requests.  Likewise, Tomcat will return cleartext responses, that will
  -be encrypted before being returned to the user's browser.  In this environment,
  -Tomcat knows that communications between the primary web server and the
  -client are taking place over a secure connection (because your application
  -needs to be able to ask about this), but it does not participate in the
  -encryption or decryption itself.</p>
  -
  -</section>
  -
  -<section name="Certificates">
  -
  -<p>In order to implement SSL, a web server must have an associated Certificate
  -for each external interface (IP address) that accepts secure connections.
  -The theory behind this design is that a server should provide some kind of
  -reasonable assurance that its owner is who you think it is, particularly
  -before receiving any sensitive information.  While a broader explanation of
  -Certificates is beyond the scope of this document, think of a Certificate
  -as a "digital driver's license" for an Internet address.  It states what
  -company the site is associated with, along with some basic contact
  -information about the site owner or administrator.</p>
  -
  -<p>This "driver's license" is cryptographically signed by its owner, and is
  -therefore extremely difficult for anyone else to forge.  For sites involved
  -in e-commerce, or any other business transaction in which authentication of
  -identity is important, a Certificate is typically purchased from a well-known
  -<em>Certificate Authority</em> (CA) such as VeriSign or Thawte.  Such
  -certificates can be electronically verified -- in effect, the Certificate
  -Authority will vouch for the authenticity of the certificates that it grants,
  -so you can believe that that Certificate is valid if you trust the Certificate
  -Authority that granted it.</p>
  -
  -<p>In many cases, however, authentication is not really a concern.  An
  -administrator may simply want to ensure that the data being transmitted and
  -received by the server is private and cannot be snooped by anyone who may be
  -eavesdropping on the connection.  Fortunately, Java provides a relatively
  -simple command-line tool, called <code>keytool</code>, which can easily create
  -a "self-signed" Certificate.  Self-signed Certificates are simply user
  -generated Certificates which have not been officially registered with any
  -well-known CA, and are therefore not really guaranteed to be authentic at all.
  -Again, this may or may not even be important, depending on your needs.</p>
  -
  -</section>
  -
  -<section name="General Tips on Running SSL">
  -
  -<p>The first time a user attempts to access a secured page on your site,
  -he or she is typically presented with a dialog containing the details of
  -the certificate (such as the company and contact name), and asked if he or she
  -wishes to accept the Certificate as valid and continue with the transaction.
  -Some browsers will provide an option for permanently accepting a given
  -Certificate as valid, in which case the user will not be bothered with a
  -prompt each time they visit your site.  Other browsers do not provide this
  -option.  Once approved by the user, a Certificate will be considered valid
  -for at least the entire browser session.</p>
  -
  -<p>Also, while the SSL protocol was designed to be as efficient as securely
  -possible, encryption/decryption is a computationally expensive process from
  -a performance standpoint.  It is not strictly necessary to run an entire
  -web application over SSL, and indeed a developer can pick and choose which
  -pages require a secure connection and which do not.  For a reasonably busy
  -site, it is customary to only run certain pages under SSL, namely those
  -pages where sensitive information could possibly be exchanged.  This would
  -include things like login pages, personal information pages, and shopping
  -cart checkouts, where credit card information could possibly be transmitted.
  -Any page within an application can be requested over a secure socket by
  -simply prefixing the address with <code>https:</code> instead of
  -<code>http:</code>.  Any pages which absolutely <strong>require</strong>
  -a secure connection should check the protocol type associated with the
  -page request and take the appropriate action of <code>https</code> is not
  -specified.</p>
  -
  -<p>Finally, using name-based virtual hosts on a secured connection can be
  -problematic.  This is a design limitation of the SSL protocol itself.  The SSL
  -handshake, where the client browser accepts the server certificate, must occur
  -before the HTTP request is accessed.  As a result, the request information
  -containing the virtual host name cannot be determined prior to authentication,
  -and it is therefore not possible to assign multiple certificates to a single
  -IP address.  If all virtual hosts on a single IP address need to authenticate
  -against the same certificate, the addition of multiple virtual hosts should not
  -interfere with normal SSL operations on the server.  Be aware, however, that
  -most client browsers will compare the server's domain name against the domain
  -name listed in the certificate, if any (applicable primarily to official,
  -CA-signed certificates).  If the domain names do not match, these browsers will
  -display a warning to the client user.  In general, only address-based virtual
  -hosts are commonly used with SSL in a production environment.</p>
  -
  -</section>
  -
  -<section name="Configuration">
  -
  -<subsection name="Download and Install JSSE">
  -
  -<p>Download the <em>Java Secure Socket Extensions</em> (JSSE) package,
  -version 1.0.2 or later, from
  -<a href="http://java.sun.com/products/jsse/">http://java.sun.com/products/jsse/</a>.
  -If you built Tomcat from source, you have probably already downloaded this
  -package.  If you are running JDK 1.4 (currently in beta), these classes have
  -been integrated directly into the JDK, so you can skip this entire step.</p>
  -
  -<p>After expanding the package, there are two ways to make it available to
  -Tomcat (choose one or the other):</p>
  -<ul>
  -<li>Make JSSE an <em>installed extension</em> by copying all three JAR files
  -    (<code>jcert.jar</code>, <code>jnet.jar</code>, and <code>jsse.jar</code>)
  -    into your <code>$JAVA_HOME/jre/lib/ext</code> directory.</li>
  -<li>Create a new environment variable <code>JSSE_HOME</code> that contains
  -    the absolute path to the directory into which you unpacked the
  -    JSSE binary distribution.</li>
  -</ul>
  -
  -</subsection>
  -
  -<subsection name="Prepare the Certificate Keystore">
  -
  -<p>Tomcat currently operates only on <code>JKS</code> format keystores.  This
  -is Java's standard "Java KeyStore" format, and is the format created by the
  -<code>keytool</code> command-line utility.  This tool is included in the JDK.
  -</p>
  -
  -<p>To import an existing certificate into a JKS keystore, please read the
  -documentation (in your JDK documentation package) about <code>keytool</code>.
  -</p>
  -
  -<p>To create a new keystore from scratch, containing a single self-signed
  -Certificate, execute the following from a terminal command line:</p>
  -<p>Windows:</p>
  -<source>
  -%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA
  -</source>
  -<p>Unix:</p>
  -<source>
  -$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA
  -</source>
  -
  -<p>(The RSA algorithm should be preferred as a secure algorithm, and this
  -also ensures general compatibility with other servers and components.)</p>
  -
  -<p>This command will create a new file, in the home directory of the user
  -under which you run it, named "<code>.keystore</code>".  To specify a
  -different location or filename, add the <code>-keystore</code> parameter,
  -followed by the complete pathname to your keystore file,
  -to the <code>keytool</code> command shown above.  You will also need to
  -reflect this new location in the <code>server.xml</code> configuration file,
  -as described later.  For example:</p>
  -<p>Windows:</p>
  -<source>
  -%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA \
  -  -keystore \path\to\my\keystore
  -</source>
  -<p>Unix:</p>
  -<source>
  -$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA \
  -  -keystore /path/to/my/keystore
  -</source>
  -
  -<p>After executing this command, you will first be prompted for the keystore
  -password.  The default password used by Tomcat is "<code>changeit</code>"
  -(all lower case), although you can specify a custom password if you like.
  -You will also need to specify the custom password in the
  -<code>server.xml</code> configuration file, as described later.</p>
  -
  -<p>Next, you will be prompted for general information about this Certificate,
  -such as company, contact name, and so on.  This information will be displayed
  -to users who attempt to access a secure page in your application, so make
  -sure that the information provided here matches what they will expect.</p>
  -
  -<p>Finally, you will be prompted for the <em>key password</em>, which is the
  -password specifically for this Certificate (as opposed to any other
  -Certificates stored in the same keystore file).  You <strong>MUST</strong>
  -use the same password here as was used for the keystore password itself.
  -(Currently, the <code>keytool</code> prompt will tell you that pressing the
  -ENTER key does this for you automatically.)</p>
  -
  -<p>If everything was successful, you now have a keystore file with a
  -Certificate that can be used by your server.</p>
  -
  -</subsection>
  -
  -<subsection name="Edit the Tomcat Configuration File">
  -
  -<p>The final step is to configure your secure socket in the
  -<code>$CATALINA_HOME/conf/server.xml</code> file, where
  -<code>$CATALINA_HOME</code> represents the directory into which you
  -installed Tomcat 4.  An example <code>&lt;Connector&gt;</code> element
  -for an SSL connector is included in the default <code>server.xml</code>
  -file installed with Tomcat.  It will look something like this:</p>
  -<source>
  -&lt;-- Define an SSL HTTP/1.1 Connector on port 8443 --&gt;
  -&lt;!--
  -&lt;Connector className="org.apache.catalina.connector.http.HttpConnector"
  -           port="8443" minProcessors="5" maxProcessors="75"
  -           enableLookups="true"
  -           acceptCount="10" debug="0" scheme="https" secure="true"&gt;
  -  &lt;Factory className="org.apache.catalina.net.SSLServerSocketFactory"
  -           clientAuth="false" protocol="TLS"/&gt;
  -&lt;/Connector&gt;
  ---&gt;
  -</source>
  -
  -<p>You will note that the Connector element itself is commented out by default,
  -so you will need to remove the comment tags around it.  Then, you can
  -customize the specified attributes as necessary.  For detailed information
  -about the various options, consult the
  -<a href="config/index.html">Server Configuration Reference</a>.  The
  -following discussion covers only those attributes of most interest when
  -setting up SSL communication.</p>
  -
  -<p>The <code>port</code> attribute (default value is 8443) is the TCP/IP
  -port number on which Tomcat will listen for secure connections.  You can
  -change this to any port number you wish (such as to the default port for
  -<code>https</code> communications, which is 443).  However, special setup
  -(outside the scope of this document) is necessary to run Tomcat on port
  -numbers lower than 1024 on many operating systems.</p>
  -
  -  <blockquote><em>
  -  <p>If you change the port number here, you should also change the
  -  value specified for the <code>redirectPort</code> attribute on the
  -  non-SSL connector.  This allows Tomcat to automatically redirect
  -  users who attempt to access a page with a security constraint specifying
  -  that SSL is required, as required by the Servlet 2.3 Specification.</p>
  -  </em></blockquote>
  -
  -<p>You will notice a <code>Factory</code> element nested inside the
  -<code>Connector</code> element.  This is where the "socket factory" used
  -by Tomcat, whenever it needs a socket on the corresponding port number,
  -is configured.  You may need to add or change the following attribute
  -values, depending on how you configured your keystore earlier:</p>
  -
  -<table border="1">
  -  <tr>
  -    <th>Attribute</th>
  -    <th>Description</th>
  -  </tr>
  -  <tr>
  -    <td><code>className</code></td>
  -    <td>The fully qualified class name of the Java class that implements
  -        this socket factory.  Do not change the default value.</td>
  -  </tr>
  -  <tr>
  -    <td><code>clientAuth</code></td>
  -    <td>Set this value to <code>true</code> if you want Tomcat to require
  -        all SSL clients to present a client Certificate in order to use
  -        this socket.</td>
  -  </tr>
  -  <tr>
  -    <td><code>keystoreFile</code></td>
  -    <td>Add this attribute if the keystore file you created is not in
  -        the default place that Tomcat expects (a file named
  -        <code>.keystore</code> in the user home directory under
  -        which Tomcat is running).  You can specify an absolute pathname,
  -        or a relative pathname that is resolved against the
  -        <code>$CATALINA_BASE</code> environment variable.</td>
  -  </tr>
  -  <tr>
  -    <td><code>keystorePass</code></td>
  -    <td>Add this element if you used a different keystore (and Certificate)
  -        password than the one Tomcat expects (<code>changeit</code>).</td>
  -  </tr>
  -  <tr>
  -    <td><code>protocol</code></td>
  -    <td>The encryption/decryption protocol to be used on this socket.
  -        Do not change the default value.</td>
  -  </tr>
  -</table>
  -
  -<p>After completing these configuration changes, you must restart Tomcat as
  -you normally do, and you should be in business.  You should be able to access
  -any web application supported by Tomcat via SSL.  For example, try:</p>
  -<source>
  -https://localhost:8443
  -</source>
  -
  -<p>and you should see the usual Tomcat splash page (unless you have modified
  -the ROOT web application).  If this does not work, the following section
  -contains some troubleshooting tips.</p>
  -
  -</subsection>
  -
  -</section>
  -
  -<section name="Troubleshooting">
  -
  -<p>Here is a list of common problems that you may encounter when setting up
  -SSL communications, and what to do about them.</p>
  -
  -<ul>
  -
  -<li>I get "java.security.NoSuchAlgorithmException" errors in my
  -    log files.
  -    <blockquote>
  -    <p>The JVM cannot find the JSSE JAR files.  Follow all of the directions to
  -    <a href="#Download and Install JSSE">download and install JSSE</a>.</p>
  -    </blockquote></li>
  -
  -<li>When Tomcat starts up, I get an exception like
  -    "java.io.FileNotFoundException: {some-directory}/{some-file} not found".
  -    <blockquote>
  -    <p>A likely explanation is that Tomcat cannot find the keystore file
  -    where it is looking.  By default, Tomcat expects the keystore file to
  -    be named <code>.keystore</code> in the user home directory under which
  -    Tomcat is running (which may or may not be the same as yours :-).  If
  -    the keystore file is anywhere else, you will need to add a
  -    <code>keystoreFile</code> attribute to the <code>&lt;Factory&gt;</code>
  -    element in the <a href="#Edit the Tomcat Configuration File">Tomcat
  -    configuration file</a>.</p>
  -    </blockquote></li>
  -
  -<li>When Tomcat starts up, I get an exception like
  -    "java.io.FileNotFoundException:  Keystore was tampered with, or
  -    password was incorrect".
  -    <blockquote>
  -    <p>Assuming that someone has not <em>actually</em> tampered with
  -    your keystore file, the most likely cause is that Tomcat is using
  -    a different password than the one you used when you created the
  -    keystore file.  To fix this, you can either go back and
  -    <a href="#Prepare the Certificate Keystore">recreate the keystore
  -    file</a>, or you can add or update the <code>keystorePass</code>
  -    attribute on the <code>&lt;Factory&gt;</code> element in the
  -    <a href="#Edit the Tomcat Configuration File">Tomcat configuration
  -    file</a>.  <strong>REMINDER</strong> - Passwords are case sensitive!</p>
  -    </blockquote></li>
  -
  -</ul>
  -
  -<p>If you are still having problems, a good source of information is the
  -<strong>TOMCAT-USER</strong> mailing list.  You can find pointers to archives
  -of previous messages on this list, as well as subscription and unsubscription
  -information, at
  -<a href="http://jakarta.apache.org/site/mail.html">http://jakarta.apache.org/site/mail.html"</a>.</p>
  -
  -</section>
  -
  -</body>
  -
  -</document>
  +<?xml version="1.0"?>
  +<!DOCTYPE document [
  +  <!ENTITY project SYSTEM "project.xml">
  +]>
  +<document>
  +
  +    &project;
  +
  +    <properties>
  +        <author email="ccain@apache.org">Christopher Cain</author>
  +        <title>SSL Configuration HOW-TO</title>
  +    </properties>
  +
  +<body>
  +
  +
  +<section name="Quick-Start Version">
  +
  +    <blockquote><em>
  +    <p>The description below uses the variable name $CATALINA_HOME
  +    to refer to the directory into which you have installed Tomcat 4,
  +    and is the base directory against which most relative paths are
  +    resolved.  However, if you have configured Tomcat 4 for multiple
  +    instances by setting a CATALINA_BASE directory, you should use
  +    $CATALINA_BASE instead of $CATALINA_HOME for each of these
  +    references.</p>
  +    </em></blockquote>
  +
  +<p>To install and configure SSL support on Tomcat 4, you need to follow
  +these simple steps.  For more information, read the rest of this HOW-TO.</p>
  +<ol>
  +<li>Download JSSE 1.0.2 (or later) from
  +   <a href="http://java.sun.com/products/jsse/">http://java.sun.com/products/jsse/</a>
  +   and either make it an <em>installed extension</em> on the system, or else
  +   set an environment variable <code>JSSE_HOME</code> that points at the
  +   directory into which you installed JSSE.</li><br/><br/>
  +<li>Create a certificate keystore by executing the following command:
  +<p>Windows:</p>
  +<source>
  +%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA
  +</source>
  +<p>Unix:</p>
  +<source>
  +$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA
  +</source>
  +<p></p>
  +    and specify a password value of "changeit".</li><br/><br/>
  +<li>Uncomment the "SSL HTTP/1.1 Connector" entry in
  +    <code>$CATALINA_HOME/conf/server.xml</code> and tweak as necessary.</li>
  +    <br/><br/>
  +</ol>
  +
  +
  +</section>
  +
  +
  +<section name="Introduction to SSL">
  +
  +<p>SSL, or Secure Socket Layer, is a technology which allows web browsers and
  +web servers to communicate over a secured connection.  This means that the data
  +being sent is encrypted by one side, transmitted, then decrypted by the other
  +side before processing.  This is a two-way process, meaning that both the
  +server AND the browser encrypt all traffic before sending out data.</p>
  +
  +<p>Another important aspect of the SSL protocol is Authentication.  This means
  +that during your initial attempt to communicate with a web server over a secure
  +connection, that server will present your web browser with a set of
  +credentials, in the form of a "Certificate", as proof the site is who and what
  +it claims to be.  In certain cases, the server may also request a Certificate
  +from your web browser, asking for proof that <em>you</em> are who you claim
  +to be.  This is known as "Client Authentication," although in practice this is
  +used more for business-to-business (B2B) transactions than with individual
  +users.  Most SSL-enabled web servers do not request Client Authentication.</p>
  +
  +</section>
  +
  +<section name="SSL and Tomcat">
  +
  +<p>It is important to note that configuring Tomcat to take advantage of
  +secure sockets is usually only necessary when running it as a stand-alone
  +web server.  When running Tomcat primarily as a Servlet/JSP container behind
  +another web server, such as Apache or Microsoft IIS, it is usually necessary
  +to configure the primary web server to handle the SSL connections from users.
  +Typically, this server will negotiate all SSL-related functionality, then
  +pass on any requests destined for the Tomcat container only after decrypting
  +those requests.  Likewise, Tomcat will return cleartext responses, that will
  +be encrypted before being returned to the user's browser.  In this environment,
  +Tomcat knows that communications between the primary web server and the
  +client are taking place over a secure connection (because your application
  +needs to be able to ask about this), but it does not participate in the
  +encryption or decryption itself.</p>
  +
  +</section>
  +
  +<section name="Certificates">
  +
  +<p>In order to implement SSL, a web server must have an associated Certificate
  +for each external interface (IP address) that accepts secure connections.
  +The theory behind this design is that a server should provide some kind of
  +reasonable assurance that its owner is who you think it is, particularly
  +before receiving any sensitive information.  While a broader explanation of
  +Certificates is beyond the scope of this document, think of a Certificate
  +as a "digital driver's license" for an Internet address.  It states what
  +company the site is associated with, along with some basic contact
  +information about the site owner or administrator.</p>
  +
  +<p>This "driver's license" is cryptographically signed by its owner, and is
  +therefore extremely difficult for anyone else to forge.  For sites involved
  +in e-commerce, or any other business transaction in which authentication of
  +identity is important, a Certificate is typically purchased from a well-known
  +<em>Certificate Authority</em> (CA) such as VeriSign or Thawte.  Such
  +certificates can be electronically verified -- in effect, the Certificate
  +Authority will vouch for the authenticity of the certificates that it grants,
  +so you can believe that that Certificate is valid if you trust the Certificate
  +Authority that granted it.</p>
  +
  +<p>In many cases, however, authentication is not really a concern.  An
  +administrator may simply want to ensure that the data being transmitted and
  +received by the server is private and cannot be snooped by anyone who may be
  +eavesdropping on the connection.  Fortunately, Java provides a relatively
  +simple command-line tool, called <code>keytool</code>, which can easily create
  +a "self-signed" Certificate.  Self-signed Certificates are simply user
  +generated Certificates which have not been officially registered with any
  +well-known CA, and are therefore not really guaranteed to be authentic at all.
  +Again, this may or may not even be important, depending on your needs.</p>
  +
  +</section>
  +
  +<section name="General Tips on Running SSL">
  +
  +<p>The first time a user attempts to access a secured page on your site,
  +he or she is typically presented with a dialog containing the details of
  +the certificate (such as the company and contact name), and asked if he or she
  +wishes to accept the Certificate as valid and continue with the transaction.
  +Some browsers will provide an option for permanently accepting a given
  +Certificate as valid, in which case the user will not be bothered with a
  +prompt each time they visit your site.  Other browsers do not provide this
  +option.  Once approved by the user, a Certificate will be considered valid
  +for at least the entire browser session.</p>
  +
  +<p>Also, while the SSL protocol was designed to be as efficient as securely
  +possible, encryption/decryption is a computationally expensive process from
  +a performance standpoint.  It is not strictly necessary to run an entire
  +web application over SSL, and indeed a developer can pick and choose which
  +pages require a secure connection and which do not.  For a reasonably busy
  +site, it is customary to only run certain pages under SSL, namely those
  +pages where sensitive information could possibly be exchanged.  This would
  +include things like login pages, personal information pages, and shopping
  +cart checkouts, where credit card information could possibly be transmitted.
  +Any page within an application can be requested over a secure socket by
  +simply prefixing the address with <code>https:</code> instead of
  +<code>http:</code>.  Any pages which absolutely <strong>require</strong>
  +a secure connection should check the protocol type associated with the
  +page request and take the appropriate action of <code>https</code> is not
  +specified.</p>
  +
  +<p>Finally, using name-based virtual hosts on a secured connection can be
  +problematic.  This is a design limitation of the SSL protocol itself.  The SSL
  +handshake, where the client browser accepts the server certificate, must occur
  +before the HTTP request is accessed.  As a result, the request information
  +containing the virtual host name cannot be determined prior to authentication,
  +and it is therefore not possible to assign multiple certificates to a single
  +IP address.  If all virtual hosts on a single IP address need to authenticate
  +against the same certificate, the addition of multiple virtual hosts should not
  +interfere with normal SSL operations on the server.  Be aware, however, that
  +most client browsers will compare the server's domain name against the domain
  +name listed in the certificate, if any (applicable primarily to official,
  +CA-signed certificates).  If the domain names do not match, these browsers will
  +display a warning to the client user.  In general, only address-based virtual
  +hosts are commonly used with SSL in a production environment.</p>
  +
  +</section>
  +
  +<section name="Configuration">
  +
  +<subsection name="Download and Install JSSE">
  +
  +<p>Download the <em>Java Secure Socket Extensions</em> (JSSE) package,
  +version 1.0.2 or later, from
  +<a href="http://java.sun.com/products/jsse/">http://java.sun.com/products/jsse/</a>.
  +If you built Tomcat from source, you have probably already downloaded this
  +package.  If you are running JDK 1.4 (currently in beta), these classes have
  +been integrated directly into the JDK, so you can skip this entire step.</p>
  +
  +<p>After expanding the package, there are two ways to make it available to
  +Tomcat (choose one or the other):</p>
  +<ul>
  +<li>Make JSSE an <em>installed extension</em> by copying all three JAR files
  +    (<code>jcert.jar</code>, <code>jnet.jar</code>, and <code>jsse.jar</code>)
  +    into your <code>$JAVA_HOME/jre/lib/ext</code> directory.</li>
  +<li>Create a new environment variable <code>JSSE_HOME</code> that contains
  +    the absolute path to the directory into which you unpacked the
  +    JSSE binary distribution.</li>
  +</ul>
  +
  +</subsection>
  +
  +<subsection name="Prepare the Certificate Keystore">
  +
  +<p>Tomcat currently operates only on <code>JKS</code> format keystores.  This
  +is Java's standard "Java KeyStore" format, and is the format created by the
  +<code>keytool</code> command-line utility.  This tool is included in the JDK.
  +</p>
  +
  +<p>To import an existing certificate into a JKS keystore, please read the
  +documentation (in your JDK documentation package) about <code>keytool</code>.
  +</p>
  +
  +<p>To create a new keystore from scratch, containing a single self-signed
  +Certificate, execute the following from a terminal command line:</p>
  +<p>Windows:</p>
  +<source>
  +%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA
  +</source>
  +<p>Unix:</p>
  +<source>
  +$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA
  +</source>
  +
  +<p>(The RSA algorithm should be preferred as a secure algorithm, and this
  +also ensures general compatibility with other servers and components.)</p>
  +
  +<p>This command will create a new file, in the home directory of the user
  +under which you run it, named "<code>.keystore</code>".  To specify a
  +different location or filename, add the <code>-keystore</code> parameter,
  +followed by the complete pathname to your keystore file,
  +to the <code>keytool</code> command shown above.  You will also need to
  +reflect this new location in the <code>server.xml</code> configuration file,
  +as described later.  For example:</p>
  +<p>Windows:</p>
  +<source>
  +%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA \
  +  -keystore \path\to\my\keystore
  +</source>
  +<p>Unix:</p>
  +<source>
  +$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA \
  +  -keystore /path/to/my/keystore
  +</source>
  +
  +<p>After executing this command, you will first be prompted for the keystore
  +password.  The default password used by Tomcat is "<code>changeit</code>"
  +(all lower case), although you can specify a custom password if you like.
  +You will also need to specify the custom password in the
  +<code>server.xml</code> configuration file, as described later.</p>
  +
  +<p>Next, you will be prompted for general information about this Certificate,
  +such as company, contact name, and so on.  This information will be displayed
  +to users who attempt to access a secure page in your application, so make
  +sure that the information provided here matches what they will expect.</p>
  +
  +<p>Finally, you will be prompted for the <em>key password</em>, which is the
  +password specifically for this Certificate (as opposed to any other
  +Certificates stored in the same keystore file).  You <strong>MUST</strong>
  +use the same password here as was used for the keystore password itself.
  +(Currently, the <code>keytool</code> prompt will tell you that pressing the
  +ENTER key does this for you automatically.)</p>
  +
  +<p>If everything was successful, you now have a keystore file with a
  +Certificate that can be used by your server.</p>
  +
  +</subsection>
  +
  +<subsection name="Edit the Tomcat Configuration File">
  +
  +<p>The final step is to configure your secure socket in the
  +<code>$CATALINA_HOME/conf/server.xml</code> file, where
  +<code>$CATALINA_HOME</code> represents the directory into which you
  +installed Tomcat 4.  An example <code>&lt;Connector&gt;</code> element
  +for an SSL connector is included in the default <code>server.xml</code>
  +file installed with Tomcat.  It will look something like this:</p>
  +<source>
  +&lt;-- Define an SSL HTTP/1.1 Connector on port 8443 --&gt;
  +&lt;!--
  +&lt;Connector className="org.apache.catalina.connector.http.HttpConnector"
  +           port="8443" minProcessors="5" maxProcessors="75"
  +           enableLookups="true"
  +           acceptCount="10" debug="0" scheme="https" secure="true"&gt;
  +  &lt;Factory className="org.apache.catalina.net.SSLServerSocketFactory"
  +           clientAuth="false" protocol="TLS"/&gt;
  +&lt;/Connector&gt;
  +--&gt;
  +</source>
  +
  +<p>You will note that the Connector element itself is commented out by default,
  +so you will need to remove the comment tags around it.  Then, you can
  +customize the specified attributes as necessary.  For detailed information
  +about the various options, consult the
  +<a href="config/index.html">Server Configuration Reference</a>.  The
  +following discussion covers only those attributes of most interest when
  +setting up SSL communication.</p>
  +
  +<p>The <code>port</code> attribute (default value is 8443) is the TCP/IP
  +port number on which Tomcat will listen for secure connections.  You can
  +change this to any port number you wish (such as to the default port for
  +<code>https</code> communications, which is 443).  However, special setup
  +(outside the scope of this document) is necessary to run Tomcat on port
  +numbers lower than 1024 on many operating systems.</p>
  +
  +  <blockquote><em>
  +  <p>If you change the port number here, you should also change the
  +  value specified for the <code>redirectPort</code> attribute on the
  +  non-SSL connector.  This allows Tomcat to automatically redirect
  +  users who attempt to access a page with a security constraint specifying
  +  that SSL is required, as required by the Servlet 2.3 Specification.</p>
  +  </em></blockquote>
  +
  +<p>You will notice a <code>Factory</code> element nested inside the
  +<code>Connector</code> element.  This is where the "socket factory" used
  +by Tomcat, whenever it needs a socket on the corresponding port number,
  +is configured.  You may need to add or change the following attribute
  +values, depending on how you configured your keystore earlier:</p>
  +
  +<table border="1">
  +  <tr>
  +    <th>Attribute</th>
  +    <th>Description</th>
  +  </tr>
  +  <tr>
  +    <td><code>className</code></td>
  +    <td>The fully qualified class name of the Java class that implements
  +        this socket factory.  Do not change the default value.</td>
  +  </tr>
  +  <tr>
  +    <td><code>clientAuth</code></td>
  +    <td>Set this value to <code>true</code> if you want Tomcat to require
  +        all SSL clients to present a client Certificate in order to use
  +        this socket.</td>
  +  </tr>
  +  <tr>
  +    <td><code>keystoreFile</code></td>
  +    <td>Add this attribute if the keystore file you created is not in
  +        the default place that Tomcat expects (a file named
  +        <code>.keystore</code> in the user home directory under
  +        which Tomcat is running).  You can specify an absolute pathname,
  +        or a relative pathname that is resolved against the
  +        <code>$CATALINA_BASE</code> environment variable.</td>
  +  </tr>
  +  <tr>
  +    <td><code>keystorePass</code></td>
  +    <td>Add this element if you used a different keystore (and Certificate)
  +        password than the one Tomcat expects (<code>changeit</code>).</td>
  +  </tr>
  +  <tr>
  +    <td><code>protocol</code></td>
  +    <td>The encryption/decryption protocol to be used on this socket.
  +        Do not change the default value.</td>
  +  </tr>
  +</table>
  +
  +<p>After completing these configuration changes, you must restart Tomcat as
  +you normally do, and you should be in business.  You should be able to access
  +any web application supported by Tomcat via SSL.  For example, try:</p>
  +<source>
  +https://localhost:8443
  +</source>
  +
  +<p>and you should see the usual Tomcat splash page (unless you have modified
  +the ROOT web application).  If this does not work, the following section
  +contains some troubleshooting tips.</p>
  +
  +</subsection>
  +
  +</section>
  +
  +<section name="Troubleshooting">
  +
  +<p>Here is a list of common problems that you may encounter when setting up
  +SSL communications, and what to do about them.</p>
  +
  +<ul>
  +
  +<li>I get "java.security.NoSuchAlgorithmException" errors in my
  +    log files.
  +    <blockquote>
  +    <p>The JVM cannot find the JSSE JAR files.  Follow all of the directions to
  +    <a href="#Download and Install JSSE">download and install JSSE</a>.</p>
  +    </blockquote></li>
  +
  +<li>When Tomcat starts up, I get an exception like
  +    "java.io.FileNotFoundException: {some-directory}/{some-file} not found".
  +    <blockquote>
  +    <p>A likely explanation is that Tomcat cannot find the keystore file
  +    where it is looking.  By default, Tomcat expects the keystore file to
  +    be named <code>.keystore</code> in the user home directory under which
  +    Tomcat is running (which may or may not be the same as yours :-).  If
  +    the keystore file is anywhere else, you will need to add a
  +    <code>keystoreFile</code> attribute to the <code>&lt;Factory&gt;</code>
  +    element in the <a href="#Edit the Tomcat Configuration File">Tomcat
  +    configuration file</a>.</p>
  +    </blockquote></li>
  +
  +<li>When Tomcat starts up, I get an exception like
  +    "java.io.FileNotFoundException:  Keystore was tampered with, or
  +    password was incorrect".
  +    <blockquote>
  +    <p>Assuming that someone has not <em>actually</em> tampered with
  +    your keystore file, the most likely cause is that Tomcat is using
  +    a different password than the one you used when you created the
  +    keystore file.  To fix this, you can either go back and
  +    <a href="#Prepare the Certificate Keystore">recreate the keystore
  +    file</a>, or you can add or update the <code>keystorePass</code>
  +    attribute on the <code>&lt;Factory&gt;</code> element in the
  +    <a href="#Edit the Tomcat Configuration File">Tomcat configuration
  +    file</a>.  <strong>REMINDER</strong> - Passwords are case sensitive!</p>
  +    </blockquote></li>
  +
  +</ul>
  +
  +<p>If you are still having problems, a good source of information is the
  +<strong>TOMCAT-USER</strong> mailing list.  You can find pointers to archives
  +of previous messages on this list, as well as subscription and unsubscription
  +information, at
  +<a href="http://jakarta.apache.org/site/mail.html">http://jakarta.apache.org/site/mail.html"</a>.</p>
  +
  +</section>
  +
  +</body>
  +
  +</document>
  
  
  

--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>