From ae0e88a5c91020a527815207dae590553fac3c2d Mon Sep 17 00:00:00 2001
From: fhanik <fhanik@13f79535-47bb-0310-9956-ffa450edef68>
Date: Tue, 17 Oct 2006 16:49:59 +0000
Subject: [PATCH] Cleaned up server.xml, added in documentation references so
 that a user can navigate from an element in server.xml to the correct
 location in the online documentation.

git-svn-id: https://svn.apache.org/repos/asf/tomcat/tc6.0.x/trunk@464958 13f79535-47bb-0310-9956-ffa450edef68
---
 conf/server.xml | 205 +++++++++++---------------------------------------------
 1 file changed, 40 insertions(+), 165 deletions(-)

diff --git a/conf/server.xml b/conf/server.xml
index 5aac397d8..bd2d98939 100644
--- a/conf/server.xml
+++ b/conf/server.xml
@@ -1,95 +1,54 @@
 <!-- Example Server Configuration File -->
-<!-- Note that component elements are nested corresponding to their
-     parent-child relationships with each other -->
-
-<!-- A "Server" is a singleton element that represents the entire JVM,
-     which may contain one or more "Service" instances.  The Server
-     listens for a shutdown command on the indicated port.
-
-     Note:  A "Server" is not itself a "Container", so you may not
-     define subcomponents such as "Valves" or "Loggers" at this level.
+<!-- Note:  A "Server" is not itself a "Container", so you may not
+     define subcomponents such as "Valves" at this level.
+     Documentation at /docs/config/server.html
  -->
-
 <Server port="8005" shutdown="SHUTDOWN">
 
-  <!-- Comment these entries out to disable JMX MBeans support used for the 
-       administration web application -->
+  <!--APR library loader. Documentation at /docs/apr.html -->
   <Listener className="org.apache.catalina.core.AprLifecycleListener" />
+  <!--Initialize Jasper prior to webapps are loaded. Documentation at /docs/jasper-howto.html -->
   <Listener className="org.apache.catalina.core.JasperListener" />
+  <!-- JMX Support for the Tomcat server. Documentation at /docs/non-existent.html -->
   <Listener className="org.apache.catalina.mbeans.ServerLifecycleListener" />
   <Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener" />
   <!--<Listener className="org.apache.catalina.storeconfig.StoreConfigLifecycleListener"/>-->
 
-  <!-- Global JNDI resources -->
+  <!-- Global JNDI resources
+       Documentation at /docs/jndi-resources-howto.html
+  -->
   <GlobalNamingResources>
-
     <!-- Test entry for demonstration purposes -->
     <Environment name="simpleValue" type="java.lang.Integer" value="30"/>
-
     <!-- Editable user database that can also be used by
-         UserDatabaseRealm to authenticate users -->
+         UserDatabaseRealm to authenticate users
+    -->
     <Resource name="UserDatabase" auth="Container"
               type="org.apache.catalina.UserDatabase"
-       description="User database that can be updated and saved"
-           factory="org.apache.catalina.users.MemoryUserDatabaseFactory"
-          pathname="conf/tomcat-users.xml" />
-
+              description="User database that can be updated and saved"
+              factory="org.apache.catalina.users.MemoryUserDatabaseFactory"
+              pathname="conf/tomcat-users.xml" />
   </GlobalNamingResources>
 
   <!-- A "Service" is a collection of one or more "Connectors" that share
-       a single "Container" (and therefore the web applications visible
-       within that Container).  Normally, that Container is an "Engine",
-       but this is not required.
-
-       Note:  A "Service" is not itself a "Container", so you may not
-       define subcomponents such as "Valves" or "Loggers" at this level.
+       a single "Container" Note:  A "Service" is not itself a "Container", 
+       so you may not define subcomponents such as "Valves" at this level.
+       Documentation at /docs/config/service.html
    -->
-
-  <!-- Define the Tomcat Stand-Alone Service -->
   <Service name="Catalina">
 
     <!-- A "Connector" represents an endpoint by which requests are received
-         and responses are returned.  Each Connector passes requests on to the
-         associated "Container" (normally an Engine) for processing.
-
-         By default, a non-SSL HTTP/1.1 Connector is established on port 8080.
-         You can also enable an SSL HTTP/1.1 Connector on port 8443 by
-         following the instructions below and uncommenting the second Connector
-         entry.  SSL support requires the following steps (see the SSL Config
-         HOWTO in the Tomcat 5 documentation bundle for more detailed
-         instructions):
-         * If your JDK version 1.3 or prior, download and install JSSE 1.0.2 or
-           later, and put the JAR files into "$JAVA_HOME/jre/lib/ext".
-         * Execute:
-             %JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA (Windows)
-             $JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA  (Unix)
-           with a password value of "changeit" for both the certificate and
-           the keystore itself.
-
-         By default, DNS lookups are enabled when a web application calls
-         request.getRemoteHost().  This can have an adverse impact on
-         performance, so you can disable it by setting the
-         "enableLookups" attribute to "false".  When DNS lookups are disabled,
-         request.getRemoteHost() will return the String version of the
-         IP address of the remote client.
+         and responses are returned. Documentation at :
+         Java HTTP Connector: /docs/config/http.html (blocking & non-blocking)
+         Java AJP  Connector: /docs/config/ajp.html
+         APR (HTTP/AJP) Connector: /docs/apr.html
+         Define a non-SSL HTTP/1.1 Connector on port 8080
     -->
-
-    <!-- Define a non-SSL HTTP/1.1 Connector on port 8080 -->
     <Connector port="8080" maxThreads="150" connectionTimeout="20000" 
                redirectPort="8443" />
-    <!-- Note : To disable connection timeouts, set connectionTimeout value
-     to 0 -->
-	
-	<!-- Note : To use gzip compression you could set the following properties :
-	
-			   compression="on" 
-			   compressionMinSize="2048" 
-			   noCompressionUserAgents="gozilla, traviata" 
-			   compressableMimeType="text/html,text/xml"
-	-->
-
-    <!-- Define a SSL HTTP/1.1 Connector on port 8443 -->
-    <!-- This connector uses the JSSE configuration, when using APR, the 
+
+    <!-- Define a SSL HTTP/1.1 Connector on port 8443
+         This connector uses the JSSE configuration, when using APR, the 
          connector should be using the OpenSSL style configuration
          described in the APR documentation -->
     <!--
@@ -100,52 +59,32 @@
     <!-- Define an AJP 1.3 Connector on port 8009 -->
     <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />
 
-    <!-- Define a Proxied HTTP/1.1 Connector on port 8082 -->
-    <!-- See proxy documentation for more information about using this. -->
-    <!--
-    <Connector port="8082" maxThreads="150" connectionTimeout="20000"
-               proxyPort="80" />
-    -->
 
     <!-- An Engine represents the entry point (within Catalina) that processes
          every request.  The Engine implementation for Tomcat stand alone
          analyzes the HTTP headers included with the request, and passes them
-         on to the appropriate Host (virtual host). -->
+         on to the appropriate Host (virtual host).
+         Documentation at /docs/config/engine.html -->
 
     <!-- You should set jvmRoute to support load-balancing via AJP ie :
     <Engine name="Standalone" defaultHost="localhost" jvmRoute="jvm1">         
     --> 
-         
-    <!-- Define the top level container in our container hierarchy -->
     <Engine name="Catalina" defaultHost="localhost">
 
-      <!--For clustering, please check out /docs/cluster-howto.html and
+      <!--For clustering, please take a look at documentation at:
+          /docs/cluster-howto.html  (simple how to)
           /docs/config/cluster.html (reference documentation) -->
       <!--
       <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"/>
       -->        
 
-
       <!-- The request dumper valve dumps useful debugging information about
-           the request headers and cookies that were received, and the response
-           headers and cookies that were sent, for all requests received by
-           this instance of Tomcat.  If you care only about requests to a
-           particular virtual host, or a particular application, nest this
-           element inside the corresponding <Host> or <Context> entry instead.
-
-           For a similar mechanism that is portable to all Servlet 2.4
-           containers, check out the "RequestDumperFilter" Filter in the
-           example application (the source for this filter may be found in
-           "$CATALINA_HOME/webapps/examples/WEB-INF/classes/filters").
-
-           Request dumping is disabled by default.  Uncomment the following
-           element to enable it. -->
+           the request and response data received and sent by Tomcat.
+           Documentation at: /docs/config/valve.html -->
       <!--
       <Valve className="org.apache.catalina.valves.RequestDumperValve"/>
       -->
 
-      <!-- Because this Realm is here, an instance will be shared globally -->
-
       <!-- This Realm uses the UserDatabase configured in the global JNDI
            resources under the key "UserDatabase".  Any edits
            that are performed against this UserDatabase are immediately
@@ -153,91 +92,27 @@
       <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
              resourceName="UserDatabase"/>
 
-      <!-- Comment out the old realm but leave here for now in case we
-           need to go back quickly -->
-      <!--
-      <Realm className="org.apache.catalina.realm.MemoryRealm" />
-      -->
-
-      <!-- Replace the above Realm with one of the following to get a Realm
-           stored in a database and accessed via JDBC -->
-
-      <!--
-      <Realm  className="org.apache.catalina.realm.JDBCRealm"
-             driverName="org.gjt.mm.mysql.Driver"
-          connectionURL="jdbc:mysql://localhost/authority"
-         connectionName="test" connectionPassword="test"
-              userTable="users" userNameCol="user_name" userCredCol="user_pass"
-          userRoleTable="user_roles" roleNameCol="role_name" />
-      -->
-
-      <!--
-      <Realm  className="org.apache.catalina.realm.JDBCRealm"
-             driverName="oracle.jdbc.driver.OracleDriver"
-          connectionURL="jdbc:oracle:thin:@ntserver:1521:ORCL"
-         connectionName="scott" connectionPassword="tiger"
-              userTable="users" userNameCol="user_name" userCredCol="user_pass"
-          userRoleTable="user_roles" roleNameCol="role_name" />
-      -->
-
-      <!--
-      <Realm  className="org.apache.catalina.realm.JDBCRealm"
-             driverName="sun.jdbc.odbc.JdbcOdbcDriver"
-          connectionURL="jdbc:odbc:CATALINA"
-              userTable="users" userNameCol="user_name" userCredCol="user_pass"
-          userRoleTable="user_roles" roleNameCol="role_name" />
-      -->
-
       <!-- Define the default virtual host
            Note: XML Schema validation will not work with Xerces 2.2.
        -->
-      <Host name="localhost" appBase="webapps"
-       unpackWARs="true" autoDeploy="true"
-       xmlValidation="false" xmlNamespaceAware="false">
+      <Host name="localhost"  appBase="webapps"
+            unpackWARs="true" autoDeploy="true"
+            xmlValidation="false" xmlNamespaceAware="false">
 
-        <!-- Place holder for brief cluster documentation, the rest will be online
-        -->
-        
-        <!-- Normally, users must authenticate themselves to each web app
-             individually.  Uncomment the following entry if you would like
-             a user to be authenticated the first time they encounter a
-             resource protected by a security constraint, and then have that
-             user identity maintained across *all* web applications contained
-             in this virtual host. -->
+        <!-- SingleSignOn valve, share authentication between web applications
+             Documentation at: /docs/config/valve.html -->
         <!--
         <Valve className="org.apache.catalina.authenticator.SingleSignOn" />
         -->
 
-        <!-- Access log processes all requests for this virtual host.  By
-             default, log files are created in the "logs" directory relative to
-             $CATALINA_HOME.  If you wish, you can specify a different
-             directory with the "directory" attribute.  Specify either a relative
-             (to $CATALINA_HOME) or absolute path to the desired directory.
-        -->
+        <!-- Access log processes all example.
+             Documentation at: /docs/config/valve.html -->
         <!--
-        <Valve className="org.apache.catalina.valves.AccessLogValve"
-                 directory="logs"  prefix="localhost_access_log." suffix=".txt"
-                 pattern="common" resolveHosts="false"/>
-        -->
-
-        <!-- Access log processes all requests for this virtual host.  By
-             default, log files are created in the "logs" directory relative to
-             $CATALINA_HOME.  If you wish, you can specify a different
-             directory with the "directory" attribute.  Specify either a relative
-             (to $CATALINA_HOME) or absolute path to the desired directory.
-             This access log implementation is optimized for maximum performance,
-             but is hardcoded to support only the "common" and "combined" patterns.
-        -->
-        <!--
-        <Valve className="org.apache.catalina.valves.FastCommonAccessLogValve"
-                 directory="logs"  prefix="localhost_access_log." suffix=".txt"
-                 pattern="common" resolveHosts="false"/>
+        <Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"  
+               prefix="localhost_access_log." suffix=".txt" pattern="common" resolveHosts="false"/>
         -->
 
       </Host>
-
     </Engine>
-
   </Service>
-
 </Server>
-- 
2.11.0