tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From craig...@apache.org
Subject cvs commit: jakarta-tomcat-4.0/webapps/tomcat-docs/config defaultcontext.xml loader.xml logger.xml manager.xml realm.xml valve.xml context.xml project.xml
Date Sat, 25 Aug 2001 20:06:31 GMT
craigmcc    01/08/25 13:06:31

  Modified:    webapps/tomcat-docs/config context.xml project.xml
  Added:       webapps/tomcat-docs/config defaultcontext.xml loader.xml
                        logger.xml manager.xml realm.xml valve.xml
  Log:
  Finish converting the contents of the Server Configuration Reference
  manual to the new documentation format.
  
  Revision  Changes    Path
  1.2       +1 -1      jakarta-tomcat-4.0/webapps/tomcat-docs/config/context.xml
  
  Index: context.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/config/context.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- context.xml	2001/08/25 03:37:39	1.1
  +++ context.xml	2001/08/25 20:06:30	1.2
  @@ -59,7 +59,7 @@
   
     <subsection name="Common Attributes">
   
  -    <p>All implementations of <strong>Host</strong>
  +    <p>All implementations of <strong>Context</strong>
       support the following attributes:</p>
   
       <attributes>
  
  
  
  1.4       +2 -3      jakarta-tomcat-4.0/webapps/tomcat-docs/config/project.xml
  
  Index: project.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/tomcat-docs/config/project.xml,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- project.xml	2001/08/25 01:14:13	1.3
  +++ project.xml	2001/08/25 20:06:30	1.4
  @@ -36,9 +36,8 @@
           <item name="Default Context"       href="defaultcontext.html"/>
           <item name="Loader"                href="loader.html"/>
           <item name="Logger"                href="logger.html"/>
  -        <item name="Manager"               href="manager.html"/>
  -        <item name="Realm"                 href="realm.htlm"/>
  -        <item name="Resources"             href="resources.html"/>
  +        <item name="Manager"               href="manager.html"/> 
  +        <item name="Realm"                 href="realm.html"/>
           <item name="Valve"                 href="valve.html"/>
       </menu>
   
  
  
  
  1.1                  jakarta-tomcat-4.0/webapps/tomcat-docs/config/defaultcontext.xml
  
  Index: defaultcontext.xml
  ===================================================================
  <?xml version="1.0"?>
  <!DOCTYPE document [
    <!ENTITY project SYSTEM "project.xml">
  ]>
  <document>
  
    &project;
  
    <properties>
      <author email="craigmcc@apache.org">Craig R. McClanahan</author>
      <title>The DefaultContext Component</title>
    </properties>
  
  <body>
  
  
  <section name="Introduction">
  
    <p>The <strong>DefaultContext</strong> element represents a subset of
    the configuration settings for a <a href="context.html">Context</a>,
    and can be nested inside an <a href="engine.html">Engine</a> or
    <a href="host.html">Host</a> element to represent <em>default
    configuration properties</em> for Contexts that are automatically
    created.</p>
  
    <p>See <a href="host.html#Automatic Application Deployment">Automatic
    Application Deployment</a> and
    <a href="host.html#User Web Applications">User Web Applications</a>
    for more information about the circumstances in which Catalina will
    automatically create Contexts for you, based on the configuration
    properties that are stored here.</p>
  
  </section>
  
  
  <section name="Attributes">
  
    <subsection name="Common Attributes">
  
      <p>All implementations of <strong>Host</strong>
      support the following attributes:</p>
  
      <attributes>
  
        <attribute name="cookies" required="false">
          <p>Set to <code>true</code> if you want cookies to be used for
          session identifier communication if supported by the client (this
          is the default).  Set to <code>false</code> if you want to disable
          the use of cookies for session identifier communication, and rely
          only on URL rewriting by the application.</p>
        </attribute>
  
        <attribute name="crossContext" required="false">
          <p>Set to <code>true</code> if you want calls within this application
          to <code>ServletContext.getContext()</code> to successfully return a
          request dispatcher for other web applications running on this virtual
          host.  Set to <code>false</code> (the default) in security
          conscious environments, to make <code>getContext()</code> always
          return <code>null</code>.</p>
        </attribute>
  
        <attribute name="reloadable" required="false">
          <p>Set to <code>true</code> if you want Catalina to monitor classes in
          <code>/WEB-INF/classes/</code> and <code>/WEB-INF/lib</code> for
          changes, and automatically reload the web application if a change
          is detected.  This feature is very useful during application
          development, but it requires significant runtime overhead and is
          not recommended for use on deployed production applications.  You
          can use the <a href="../manager-howto.html">Manager</a> web
          application, however, to trigger reloads of deployed applications
          on demand.</p>
        </attribute>
  
        <attribute name="useNaming" required="false">
          <p>Set to <code>true</code> (the default) to have Catalina enable a
          JNDI <code>InitialContext</code> for this web application that is
          compatible with Java2 Enterprise Edition (J2EE) platform
          conventions.</p>
        </attribute>
  
        <attribute name="wrapperClass" required="false">
          <p>Java class name of the <code>org.apache.catalina.Wrapper</code>
          implementation class that will be used for servlets managed by this
          Context.  If not specified, a standard default value will be used.</p>
        </attribute>
  
      </attributes>
  
    </subsection>
  
  
    <subsection name="Standard Implementation">
  
      <p>The standard implementation of <strong>DefaultContext</strong> is
      <strong>org.apache.catalina.core.DefaultContext</strong>.
      It supports the following additional attributes (in addition to the
      common attributes listed above):</p>
  
      <attributes>
      </attributes>
  
    </subsection>
  
  
  </section>
  
  
  <section name="Nested Components">
  
  <!--
    <p>You can nest at most one instance of the following utility components
    by nesting a corresponding element inside your
    <strong>DefaultContext</strong> element:</p>
    <ul>
    <li><a href="loader.html"><strong>Loader</strong></a> -
        Configure the web application class loader that will be used to load
        servlet and bean classes for each web application.  Normally, the
        default configuration of the class loader will be sufficient.</li>
    <li><a href="logger.html"><strong>Logger</strong></a> -
        Configure a logger that will receive
        and process all log messages for each <strong>Context</strong>.  This
        includes application messages logged via calls to
        <code>ServletContext.log()</code>.</li>
    <li><a href="manager.html"><strong>Manager</strong></a> -
        Configure the session manager that will be used to create, destroy,
        and persist HTTP sessions for each web application.  Normally, the
        default configuration of the session manager will be sufficient.</li>
    <li><a href="realm.html"><strong>Realm</strong></a> -
        Configure a realm that will allow its
        database of users, and their associated roles, to be utilized solely
        for each particular web application.  If not specified, this web
        application will utilize the Realm associated with the owning
        <a href="host.html">Host</a> or <a href="engine.html">Engine</a>.</li>
    <li><a href="resources.html"><strong>Resources</strong></a> -
        Configure the resource manager that will be used to access the static
        resources associated with each web application.  Normally, the
        default configuration of the resource manager will be sufficient.</li>
    </ul>
  -->
  
  </section>
  
  
  <section name="Special Features">
  
  
    <subsection name="Lifecycle Listeners">
  
      <p>If you have implemented a Java object that needs to know when this
      <strong>Context</strong> is started or stopped, you can declare it by
      nesting a <strong>Listener</strong> element inside this element.  The
      class name you specify must implement the
      <code>org.apache.catalina.LifecycleListener</code> interface, and
      it will be notified about the occurrence of the coresponding
      lifecycle events.  Configuration of such a listener looks like this:</p>
  
  <source>
  &lt;DefaultContext  ...&gt;
    ...
    &lt;Listener className="com.mycompany.mypackage.MyListener" ... &gt;
    ...
  &lt;/DefaultContext&gt;
  </source>
  
      <p>Note that a Listener can have any number of additional properties
      that may be configured from this element.  Attribute names are matched
      to corresponding JavaBean property names using the standard property
      method naming patterns.</p>
  
    </subsection>
  
  
  </section>
  
  
  </body>
  
  
  </document>
  
  
  
  1.1                  jakarta-tomcat-4.0/webapps/tomcat-docs/config/loader.xml
  
  Index: loader.xml
  ===================================================================
  <?xml version="1.0"?>
  <!DOCTYPE document [
    <!ENTITY project SYSTEM "project.xml">
  ]>
  <document>
  
    &project;
  
    <properties>
      <author email="craigmcc@apache.org">Craig R. McClanahan</author>
      <title>The Loader Component</title>
    </properties>
  
  <body>
  
  
  <section name="Introduction">
  
    <p>The <strong>Loader</strong> element represents the <em>web
    application class loader</em> that will be used to load Java
    classes and resources for your web application.  Such
    a class loader must follow the requirements of the Servlet
    Specification, and load classes from the following locations:</p>
    <ul>
    <li>From the <code>/WEB-INF/classes</code> directory inside your
        web application.</li>
    <li>From JAR files in the <code>/WEB-INF/lib</code> directory
        inside your web application.</li>
    <li>From resources made available by Catalina to all web
        applications globally.</li>
    </ul>
  
    <p>A Loader element MAY be nested inside a <a href="context.html">Context</a>
    component.  If it is not included, a default Loader configuration will be
    created automatically, which is sufficient for most requirements.</p>
  
    <p>For a more in-depth description of the class loader hierarchy
    that is implemented by Catalina, see <strong>FIXME - Reference</strong>.</p>
  
  </section>
  
  
  <section name="Attributes">
  
    <subsection name="Common Attributes">
  
      <p>All implementations of <strong>Loader</strong>
      support the following attributes:</p>
  
      <attributes>
  
        <attribute name="className" required="false">
          <p>Java class name of the implementation to use.  This class must
          implement the <code>org.apache.catalina.Loader</code> interface.
          If not specified, the standard value (defined below) will be used.</p>
        </attribute>
  
        <attribute name="delegate" required="false">
          <p>Set to <code>true</code> if you want the class loader to follow
          the standard Java2 delegation model, and attempt to load classes from
          parent class loaders <strong>before</strong> looking inside the web
          application.  Set to <code>false</code> (the default) to have the
          class loader look inside the web application first, before asking
          parent class loaders to find requested classes or resources.</p>
        </attribute>
  
        <attribute name="reloadable" required="false">
          <p>Set to <code>true</code> if you want Catalina to monitor classes in
          <code>/WEB-INF/classes/</code> and <code>/WEB-INF/lib</code> for
          changes, and automatically reload the web application if a change
          is detected.  This feature is very useful during application
          development, but it requires significant runtime overhead and is
          not recommended for use on deployed production applications.  You
          can use the <a href="../manager-howto.html">Manager</a> web
          application, however, to trigger reloads of deployed applications
          on demand.</p>
  
          <p><strong>NOTE</strong> - The value for this property will be
          inherited from the <code>reloadable</code> attribute you set on
          the surrounding <a href="context.html">Context</a> component,
          and any value you explicitly set here will be replaced.</p>
        </attribute>
  
      </attributes>
  
    </subsection>
  
  
    <subsection name="Standard Implementation">
  
      <p>The standard implementation of <strong>Loader</strong> is
      <strong>org.apache.catalina.loader.WebappLoader</strong>.
      It supports the following additional attributes (in addition to the
      common attributes listed above):</p>
  
      <attributes>
  
        <attribute name="checkInterval" required="false">
          <p>The number of seconds between checks for modified classes and
          resources, if <code>reloadable</code> has been set to
          <code>true</code>.  The default is 15 seconds.</p>
        </attribute>
  
        <attribute name="debug" required="false">
          <p>The level of debugging detail logged by this <strong>Engine</strong>
          to the associated <a href="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="loaderClass" required="false">
          <p>Java class name of the <code>java.lang.ClassLoader</code>
          implementation class to use.  If not specified, the default value is
          <code>org.apache.catalina.loader.WebappClassLoader</code>.</p>
        </attribute>
  
        <attribute name="workDir" required="false">
          <p>Pathname to a scratch directory to be provided by this Context
          for temporary read-write use by servlets within the associated web
          application.  This directory will be made visible to servlets in the
          web application by a servlet context attribute (of type
          <code>java.io.File</code>) named
          <code>javax.servlet.context.tempdir</code> as described in the
          Servlet Specification.  If not specified, a suitable directory
          underneath <code>$CATALINA_HOME/work</code> will be provided.</p>
        </attribute>
  
      </attributes>
  
    </subsection>
  
  
  </section>
  
  
  <section name="Nested Components">
  
    <p>No components may be nested inside a <strong>Loader</strong> element.</p>
  
  </section>
  
  
  <section name="Special Features">
  
    <p>No special features are associated with a <strong>Loader</strong>
    element.</p>
  
  </section>
  
  
  </body>
  
  
  </document>
  
  
  
  1.1                  jakarta-tomcat-4.0/webapps/tomcat-docs/config/logger.xml
  
  Index: logger.xml
  ===================================================================
  <?xml version="1.0"?>
  <!DOCTYPE document [
    <!ENTITY project SYSTEM "project.xml">
  ]>
  <document>
  
    &project;
  
    <properties>
      <author email="craigmcc@apache.org">Craig R. McClanahan</author>
      <title>The Logger Component</title>
    </properties>
  
  <body>
  
  
  <section name="Introduction">
  
    <p>A <strong>Logger</strong> element represents a destination for
    logging, debugging, and error messages (including stack tracebacks)
    for a Catalina container (<a href="engine.html">Engine</a>,
    <a href="host.html">Host</a>, or <a href="context.html">Context</a>).
    In addition, Loggers associated with an Engine or a Host are automatically
    inherited by lower-level containers, unless explicitly overridden.</p>
  
    <p>For a more in-depth description of the class loader hierarchy
    that is implemented by Catalina, see <strong>FIXME - Reference</strong>.</p>
  
  </section>
  
  
  <section name="Attributes">
  
    <subsection name="Common Attributes">
  
      <p>All implementations of <strong>Logger</strong>
      support the following attributes:</p>
  
      <attributes>
  
        <attribute name="className" required="true">
          <p>Java class name of the implementation to use.  This class must
          implement the <code>org.apache.catalina.Logger</code> interface.</p>
        </attribute>
  
        <attribute>
          <p>The verbosity level for this logger.  Messages with a higher
          verbosity level than the specified value will be silently ignored.
          Available levels are 0 (fatal messages only), 1 (errors), 2
          (warnings), 3 (information), and 4 (debug).  If not specified, the
          default value will be 1 (error).</p>
  
          <p><strong>NOTE</strong> - Only messages logged with an explicit
          verbosity level are compared to this value.  Messages logged with
          no explicit verbosity level are logged unconditionally.</p>
        </attribute>
  
      </attributes>
  
    </subsection>
  
  
    <subsection name="Standard Implementation">
  
      <p>Unlike most Catalina components, there are several standard
      <strong>Logger</strong> implementations available.  As a result,
      the <code>className</code> attribute MUST be used to select the
      implementation you wish to use.</p>
  
      <h3>File Logger (org.apache.catalina.logger.FileLogger)</h3>
  
      <p>The <strong>File Logger</strong> records all logged messages to
      disk file(s) in a specified directory.  The actual filenames of the
      log files are created from a configured prefix, the current date in
      YYYY-MM-DD format, and a configured suffix.  On the first logged
      message after midnight each day, the current log file will be closed
      and a new file opened for the new date, without having to shut down
      Catalina in order to perform this switch.</p>
  
      <p>The File Logger supports the following attributes:</p>
  
      <attributes>
  
        <attribute name="directory" required="false">
          <p>Absolute or relative pathname of a directory in which log files
          created by this logger will be placed.  If a relative path is
          specified, it is interpreted as relative to $CATALINA_HOME.  If
          no directory attribute is specified, the default value is "logs"
          (relative to $CATALINA_HOME).</p>
        </attribute>
  
        <attribute name="prefix" required="false">
          <p>The prefix added to the start of each log file's name.  If not
          specified, the default value is "catalina.".  To specify no prefix,
          use a zero-length string.</p>
        </attribute>
  
        <attribute name="suffix" required="false">
          <p>The suffix added to the end of each log file's name.  If not
          specified, the default value is ".log".  To specify no suffix,
          use a zero-length string.</p>
        </attribute>
  
        <attribute name="timestamp" required="false">
          <p>Set to <code>true</code> to cause all logged messages to be
          date and time stamped.  Set to <code>false</code> (the default)
          to skip date/time stamping.</p>
        </attribute>
  
      </attributes>
  
      <h3>Standard Error Logger (org.apache.catalina.logger.SystemErrLogger)</h3>
  
      <p>The <strong>Standard Error Logger</strong> records all logged messages
      to whatever stream the standard error output of Catalina is pointed at.
      The default Catalina startup script points this at file
      <code>logs/catalina.out</code> relative to $CATALINA_HOME.  This
      logger supports no additional attributes.</p>
  
      <h3>Standard Output Logger (org.apache.catalina.logger.SystemOutLogger)</h3>
  
      <p>The <strong>Standard Output Logger</strong> records all logged messages
      to whatever stream the standard output of Catalina is pointed at.
      The default Catalina startup script points this at file
      <code>logs/catalina.out</code> relative to $CATALINA_HOME.  This
      logger supports no additional attributes.</p>
  
    </subsection>
  
  
  </section>
  
  
  <section name="Nested Components">
  
    <p>No components may be nested inside a <strong>Logger</strong> element.</p>
  
  </section>
  
  
  <section name="Special Features">
  
    <p>No special features are associated with a <strong>Logger</strong>
    element.</p>
  
  </section>
  
  
  </body>
  
  
  </document>
  
  
  
  1.1                  jakarta-tomcat-4.0/webapps/tomcat-docs/config/manager.xml
  
  Index: manager.xml
  ===================================================================
  <?xml version="1.0"?>
  <!DOCTYPE document [
    <!ENTITY project SYSTEM "project.xml">
  ]>
  <document>
  
    &project;
  
    <properties>
      <author email="craigmcc@apache.org">Craig R. McClanahan</author>
      <title>The Manager Component</title>
    </properties>
  
  <body>
  
  
  <section name="Introduction">
  
    <p>The <strong>Manager</strong> element represents the <em>session
    manager</em> that will be used to create and maintain HTTP sessions
    as requested by the associated web application.</p>
  
    <p>A Manager element MAY be nested inside a
    <a href="context.html">Context</a> component.  If it is not included,
    a default Manager configuration will be created automatically, which
    is sufficient for most requirements.</p>
  
  </section>
  
  
  <section name="Attributes">
  
    <subsection name="Common Attributes">
  
      <p>All implementations of <strong>Manager</strong>
      support the following attributes:</p>
  
      <attributes>
  
        <attribute name="className" required="false">
          <p>Java class name of the implementation to use.  This class must
          implement the <code>org.apache.catalina.Manager</code> interface.
          If not specified, the standard value (defined below) will be used.</p>
        </attribute>
  
        <attribute name="distributable" required="false">
          <p>Set to <code>true</code> to ask the session manager to enforce
          the restrictions described in the Servlet Specification on
          distributable applications (primarily, this would mean that all
          session attributes must implement <code>java.io.Serializable</code>).
          Set to <code>false</code> (the default) to not enforce these
          restrictions.</p>
  
          <p><strong>NOTE</strong> - The value for this property is inherited
          automatically based on the presence or absence of the
          <code>&lt;distributable&gt;</code> element in the web application
          deployment descriptor (<code>/WEB-INF/web.xml</code>).</p>
        </attribute>
  
        <attribute name="maxInactiveInterval" required="false">
          <p>The default maximum inactive interval (in minutes) for Sessions
          created by this Manager.  If not specified, the default value is
          sixty (60) minutes.</p>
  
          <p><strong>NOTE</strong> - The value for this property is inherited
          automatically if you specify a <code>&lt;session-timeout&gt;</code>
          element in the web application deployment descriptor
          (<code>/WEB-INF/web.xml</code>).</p>
        </attribute>
  
      </attributes>
  
    </subsection>
  
  
    <subsection name="Standard Implementation">
  
      <p>The standard implementation of <strong>Manager</strong> is
      <strong>org.apache.catalina.session.StandardManager</strong>.
      It supports the following additional attributes (in addition to the
      common attributes listed above):</p>
  
      <attributes>
  
        <attribute name="algorithm" required="false">
          <p>Name of the <em>Message Digest</em> algorithm used to calculate
          session identifiers produced by this Manager.  This value must
          be supported by the <code>java.security.MessageDigest</code> class.
          If not specified, the default value is "MD5".</p>
        </attribute>
  
        <attribute name="checkInterval" required="false">
          <p>The number of seconds between checks for expired sessions
          for this manager.  The default value is 60 seconds.</p>
        </attribute>
  
        <attribute name="debug" required="false">
          <p>The level of debugging detail logged by this <strong>Engine</strong>
          to the associated <a href="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="entropy" required="false">
          <p>A String value that is utilized when seeding the random number
          generator used to create session identifiers for this Manager.
          If not specified, a semi-useful value is calculated, but a long
          String value should be specified in security-conscious
          environments.</p>
        </attribute>
  
        <attribute name="maxActiveSessions" required="false">
          <p>The maximum number of active sessions that will be created by
          this Manager, or -1 (the default) for no limit.</p>
        </attribute>
  
        <attribute name="pathname" required="false">
          <p>Absolute or relative (to the work directory for this Context)
          pathname of the file in which session state will be preserved
          across application restarts, if possible.  The default is
          "SESSIONS.ser".  See <a href="#Restart Persistence">Restart
          Persistence</a> for more information.</p>
        </attribute>
  
        <attribute name="randomClass" required="false">
          <p>Java class name of the <code>java.util.Random</code>
          implementation class to use.  If not specified, the default value is
          <code>java.security.SecureRandom</code>.</p>
        </attribute>
  
      </attributes>
  
    </subsection>
  
  
  </section>
  
  
  <section name="Nested Components">
  
    <p>No components may be nested inside a <strong>Manager</strong> element.</p>
  
  </section>
  
  
  <section name="Special Features">
  
  
    <subsection name="Restart Persistence">
  
      <p>Whenver Catalina is shut down normally and restarted, or when an
      application reload is triggered, the standard Manager implementation
      will attempt to serialize all currently active sessions to a disk
      file located via the <code>pathname</code> attribute.  All such saved
      sessions will then be deserialized and activated (assuming they have
      not expired in the mean time) when the application reload is completed.</p>
  
      <p>In order to successfully restore the state of session attributes,
      all such attributes MUST implement the <code>java.io.Serializable</code>
      interface.  You MAY cause the Manager to enforce this restriction by
      including the <code>&lt;distributable&gt;</code> element in your web
      application deployment descriptor (<code>/WEB-INF/web.xml</code>).</p>
  
    </subsection>
  
  </section>
  
  
  </body>
  
  
  </document>
  
  
  
  1.1                  jakarta-tomcat-4.0/webapps/tomcat-docs/config/realm.xml
  
  Index: realm.xml
  ===================================================================
  <?xml version="1.0"?>
  <!DOCTYPE document [
    <!ENTITY project SYSTEM "project.xml">
  ]>
  <document>
  
    &project;
  
    <properties>
      <author email="craigmcc@apache.org">Craig R. McClanahan</author>
      <title>The Realm Component</title>
    </properties>
  
  <body>
  
  
  <section name="Introduction">
  
    <p>A <strong>Realm</strong> element represents a "database" of usernames,
    passwords, and <em>roles</em> (similar to Unix <em>groups</em>) assigned
    to those users.  Different implementations of Realm allow Catalina to be
    integrated into environments where such authentication information is already
    being created and maintained, and then utilize that information to implement
    <em>Container Managed Security</em> as described in the Servlet
    Specification.</p>
  
    <p>You may nest a Realm inside any Catalina container
    <a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or
    <a href="context.html">Context</a>).  In addition, Realms associated with
    an Engine or a Host are automatically inherited by lower-level
    containers, unless explicitly overridden.</p>
  
    <p>For more in-depth information about container managed security in web
    applications, see <strong>FIXME - link to "Container Managed Security Guide"
    in the application developer's section</strong>.  For more in-depth
    information about configuing and using the standard Realm component
    implementations, see <strong>FIXME - link to "Realm Configuration HOW-TO"
    in the administrator's section</strong>.</p>
  
  </section>
  
  
  <section name="Attributes">
  
    <subsection name="Common Attributes">
  
      <p>All implementations of <strong>Realm</strong>
      support the following attributes:</p>
  
      <attributes>
  
        <attribute name="className" required="true">
          <p>Java class name of the implementation to use.  This class must
          implement the <code>org.apache.catalina.Realm</code> interface.</p>
        </attribute>
  
      </attributes>
  
    </subsection>
  
  
    <subsection name="Standard Implementation">
  
      <p>Unlike most Catalina components, there are several standard
      <strong>Realm</strong> implementations available.  As a result,
      the <code>className</code> attribute MUST be used to select the
      implementation you wish to use.</p>
  
      <h3>JDBC Database Realm (org.apache.catalina.realm.JDBCRealm)</h3>
  
      <p>The <strong>JDBC Database Realm</strong> connects Catalina to
      a relational database, accessed through an appropriate JDBC driver,
      to perform lookups of usernames, passwords, and their associated
      roles.  Because the lookup is done each time that it is required,
      changes to the database will be immediately reflected in the
      information used to authenticate new logins.</p>
  
      <p>A rich set of additional attributes lets you configure the required
      connection to the underlying database, as well as the table and
      column names used to retrieve the required information:</p>
  
      <attributes>
  
        <attribute name="connectionName" required="true">
          <p>The database username to use when establishing the JDBC
          connection.</p>
        </attribute>
  
        <attribute name="connectionPassword" required="true">
          <p>The database password to use when establishing the JDBC
          connection.</p>
        </attribute>
  
        <attribute name="connectionURL" required="true">
          <p>The connection URL to be passed to the JDBC driver when
          establishing a database connection.</p>
        </attribute>
  
        <attribute name="digest" required="false">
          <p>The name of the <code>MessageDigest</code> algorithm used
          to encode user passwords stored in the database.  If not specified,
          user passwords are assumed to be stored in clear-text.</p>
        </attribute>
  
        <attribute name="driverName" required="true">
          <p>Fully qualified Java class name of the JDBC driver to be
          used to connect to the authentication database.</p>
        </attribute>
  
        <attribute name="roleNameCol" required="true">
          <p>Name of the column, in the "user roles" table, which contains
          a role name assigned to the corresponding user.</p>
        </attribute>
  
        <attribute name="userCredCol" required="true">
          <p>Name of the column, in the "users" table, which contains
          the user's credentials (i.e. password(.  If a value for the
          <code>digest</code> attribute is specified, this component
          will assume that the passwords have been encoded with the
          specified algorithm.  Otherwise, they will be assumed to be
          in clear text.</p>
        </attribute>
  
        <attribute name="userNameCol" required="true">
          <p>Name of the column, in the "users" and "user roles" table,
          that contains the user's username.</p>
        </attribute>
  
        <attribute name="userRoleTable" required="true">
          <p>Name of the "user roles" table, which must contain columns
          named by the <code>userNameCol</code> and <code>roleNameCol</code>
          attributes.</p>
        </attribute>
  
        <attribute name="userTable" required="true">
          <p>Name of the "users" table, which must contain columns named
          by the <code>userNameCol</code> and <code>userCredCol</code>
          attributes.</p>
        </attribute>
  
      </attributes>
  
      <p>See <strong>FIXME - Nested pointer into HOW-TO</strong> for more
      information on setting up container managed security using the
      JDBC Database Realm component.</p>
  
  
      <h3>JNDI Directory Realm (org.apache.catalina.realm.JNDIRealm)</h3>
  
  
      <p>The <strong>JNDI Directory Realm</strong> connects Catalina to
      an LDAP Directory, accessed through an appropriate JNDI driver,
      to perform lookups of usernames, passwords, and their associated
      roles.  Because the lookup is done each time that it is required,
      changes to the directory will be immediately reflected in the
      information used to authenticate new logins.</p>
  
      <p>A rich set of additional attributes lets you configure the required
      connection to the underlying directory, as well as the element and
      attribute names used to retrieve the required information:</p>
  
      <attributes>
  
        <attribute name="connectionName" required="true">
          <p>The directory username to use when establishing the JNDI
          connection.</p>
        </attribute>
  
        <attribute name="connectionPassword" required="true">
          <p>The directory password to use when establishing the JNDI
          connection.</p>
        </attribute>
  
        <attribute name="connectionURL" required="true">
          <p>The connection URL to be passed to the JNDI driver when
          establishing a connection to the directory.</p>
        </attribute>
  
        <attribute name="contextFactory" required="false">
          <p>Fully qualified Java class name of the factory class used
          to acquire our JNDI <code>InitialContext</code>.  By default,
          assumes that the standard JNDI LDAP provider will be utilized.</p>
        </attribute>
  
        <attribute name="roleBase" required="true">
          <p>The base directory element for performing role searches.</p>
        </attribute>
  
        <attribute name="roleName" required="true">
          <p>The name of the directory attribute to retrieve when selecting
          the assigned roles for a user.</p>
        </attribute>
  
        <attribute name="roleSearch" required="true">
          <p>The LDAP search expression to use when selecting roles for a
          particular user, with <code>{0}</code> marking where the actual
          username should be inserted.</p>
        </attribute>
  
        <attribute name="roleSubtree" required="true">
          <p>Set to <code>true</code> to search subtrees of the elements
          selected by the <code>roleSearch</code> search expression.  Set
          to <code>false</code> to not search subtrees.</p>
        </attribute>
  
        <attribute name="userPassword" required="true">
          <p>Name of the LDAP element containing the user's password.</p>
        </attribute>
  
        <attribute name="userPattern" required="true">
          <p>The LDAP search expression to use when retrieving the attributes
          of a particular user, with <code>{0}</code> marking where the
          actual username should be inserted.</p>
        </attribute>
  
      </attributes>
  
      <p>See <strong>FIXME - Nested pointer into HOW-TO</strong> for more
      information on setting up container managed security using the
      JNDI Directory Realm component.</p>
  
  
      <h3>Memory Based Realm (org.apache.catalina.realm.MemoryRealm)</h3>
  
      <p>The <strong>Memory Based Realm</strong> is a simple Realm implementation
      that reads user information from an XML format, and represents it as a
      collection of Java objects in memory.  This implementation is intended
      solely to get up and running with container managed security - it is NOT
      intended for production use.  As such, there are no mechanisms for
      updating the in-memory collection of users when the content of the
      underlying data file is changed.</p>
  
      <p>The Memory Based Realm implementation supports the following
      additional attributes:</p>
  
      <attributes>
  
        <attribute name="pathname" required="false">
          <p>Absolute or relative (to $CATALINA_HOME) pathname to the XML file
          containing our user information.  See below for details on the
          XML element format required.  If no pathname is specified, the
          default value is <code>conf/tomcat-users.xml</code>.</p>
        </attribute>
  
      </attributes>
  
      <p>The XML document referenced by the <code>pathname</code> attribute must
      conform to the following requirements:</p>
      <ul>
      <li>The root (outer) element must be <code>&lt;tomcat-users&gt;</code>.
          </li>
      <li>Each authorized user must be represented by a single XML element
          <code>&lt;user&gt;</code>, nested inside the root element.</li>
      <li>Each <code>&lt;user&gt;</code> element must have the following
          attributes:
          <ul>
          <li><strong>name</strong> - Username of this user (must be unique
              within this file).</li>
          <li><strong>password</strong> - Password of this user (in
              clear text).</li>
          <li><strong>roles</strong> - Comma-delimited list of the role names
              assigned to this user.</li>
          </ul></li>
      </ul>
  
      <p>See <strong>FIXME - Nested pointer into HOW-TO</strong> for more
      information on setting up container managed security using the
      Memory Based Realm component.</p>
  
  
    </subsection>
  
  
  </section>
  
  
  <section name="Nested Components">
  
    <p>No components may be nested inside a <strong>Realm</strong> element.</p>
  
  </section>
  
  
  <section name="Special Features">
  
    <p>See <a href="host.html">Single Sign On</a> for information about
    configuring Single Sign On support for a virtual host.</p>
  
  </section>
  
  
  </body>
  
  
  </document>
  
  
  
  1.1                  jakarta-tomcat-4.0/webapps/tomcat-docs/config/valve.xml
  
  Index: valve.xml
  ===================================================================
  <?xml version="1.0"?>
  <!DOCTYPE document [
    <!ENTITY project SYSTEM "project.xml">
  ]>
  <document>
  
    &project;
  
    <properties>
      <author email="craigmcc@apache.org">Craig R. McClanahan</author>
      <title>The Valve Component</title>
    </properties>
  
  <body>
  
  
  <section name="Introduction">
  
    <p>A <strong>Valve</strong> element represents a comonent that will be
    inserted into the request processing pipeline for the associated
    Catalina container (<a href="engine.html">Engine</a>,
    <a href="host.html">Host</a>, or <a href="context.html">Context</a>).
    Individual Valves have distinct processing capabilities, and are
    described individually below.</p>
  
  </section>
  
  
  <section name="Access Log Valve">
  
    <subsection name="Introduction">
  
      <p>The <strong>Access Log Valve</strong> creates log files in the same
      format as those created by standard web servers.  These logs can later
      be analyzed by standard log analysis tools to track page hit counts,
      user session activity, and so on.  The Access Log Valve shares many
      configuration and behavior characteristics of the
      <a href="logger.html#Standard Implementation">File Logger</a>, including
      the automatic rollover of log files at midnight each night.  An
      Access Log Valve can be associated with any Catalina container, and
      will record ALL requests processed by that container.</p>
  
    </subsection>
  
    <subsection name="Attributes">
  
      <p>The <strong>Access Log Valve</strong> supports the following
      configuration attributes:</p>
  
      <attributes>
  
        <attribute name="className" required="true">
          <p>Java class name of the implementation to use.  This MUST be set to
          <strong>org.apache.catalina.valve.AccessLogValve</strong>.</p>
        </attribute>
  
        <attribute name="directory" required="false">
          <p>Absolute or relative pathname of a directory in which log files
          created by this valve will be placed.  If a relative path is
          specified, it is interpreted as relative to $CATALINA_HOME.  If
          no directory attribute is specified, the default value is "logs"
          (relative to $CATALINA_HOME).</p>
        </attribute>
  
        <attribute name="pattern" required="false">
          <p>A formatting layout identifying the various information fields
          from the request and response to be logged, or the word
          <code>common</code> or <code>combined</code> to select a
          standard format.  See below for more information on configuring
          this attribute.</p>
        </attribute>
  
        <attribute name="prefix" required="false">
          <p>The prefix added to the start of each log file's name.  If not
          specified, the default value is "access_log.".  To specify no prefix,
          use a zero-length string.</p>
        </attribute>
  
        <attribute name="resolveHosts" required="false">
          <p>Set to <code>true</code> to convert the IP address of the remote
          host into the corresponding host name via a DNS lookup.  Set to
          <code>false</code> to skip this lookup, and report the remote IP
          address instead.</p>
        </attribute>
  
        <attribute name="suffix" required="false">
          <p>The suffix added to the end of each log file's name.  If not
          specified, the default value is "".  To specify no suffix,
          use a zero-length string.</p>
        </attribute>
  
      </attributes>
  
      <p>Values for the <code>pattern</code> attribute are made up of literal
      text strings, combined with pattern identifiers prefixed by the "%"
      character to cause replacement by the corresponding variable value from
      the current request and response.  The following pattern codes are
      supported:</p>
      <ul>
      <li><b>%a</b> - Remote IP address</li>
      <li><b>%A</b> - Local IP address</li>
      <li><b>%b</b> - Bytes sent, excluding HTTP headers, or '-' if zero</li>
      <li><b>%B</b> - Bytes sent, excluding HTTP headers</li>
      <li><b>%h</b> - Remote host name (or IP address if
          <code>resolveHosts</code> is false)</li>
      <li><b>%H</b> - Request protocol</li>
      <li><b>%l</b> - Remote logical username from identd (always returns
          '-')</li>
      <li><b>%m</b> - Request method (GET, POST, etc.)</li>
      <li><b>%p</b> - Local port on which this request was received</li>
      <li><b>%q</b> - Query string (prepended with a '?' if it exists)</li>
      <li><b>%r</b> - First line of the request (method and request URI)</li>
      <li><b>%s</b> - HTTP status code of the response</li>
      <li><b>%t</b> - Date and time, in Common Log Format</li>
      <li><b>%u</b> - Remote user that was authenticated (if any), else '-'</li>
      <li><b>%U</b> - Requested URL path</li>
      <li><b>%v</b> - Local server name</li>
      </ul>
  
      <p>The shorthand pattern name <code>common</code> (which is also the
      default) corresponds to <strong>%h %l %u %t "%r" %s %b"</strong>.</p>
  
      <p>The shorthand pattern name <code>combined</code> appends the
      values of the <code>Referer</code> and <code>User-Agent</code> headers,
      each in double quotes, to the <code>common</code> pattern
      described in the previous paragraph.</p>
  
    </subsection>
  
  </section>
  
  
  <section name="Remote Address Filter">
  
    <subsection name="Introduction">
  
      <p>The <strong>Remote Address Filter</strong> allows you to compare the
      IP address of the client that submitted this request against one or more
      <em>regular expressions</em>, and either allow the request to continue
      or refuse to process the request from this client.  A Remote Address
      Filter can be associated with any Catalina container
      (<a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or
      <a href="context.html">Context</a>), and must accept any request
      presented to this container for processing before it will be passed on.</p>
  
    </subsection>
  
    <subsection name="Attributes">
  
      <p>The <strong>Remote Address Filter</strong> supports the following
      configuration attributes:</p>
  
      <attributes>
  
        <attribute name="className" required="true">
          <p>Java class name of the implementation to use.  This MUST be set to
          <strong>org.apache.catalina.valve.RemoteAddrValve</strong>.</p>
        </attribute>
  
        <attribute name="accept" required="false">
          <p>A comma-separated list of <em>regular expression</em> patterns
          that the remote client's IP address is compared to.  If this attribute
          is specified, the remote address MUST match for this request to be
          accepted.  If this attribute is not specified, all requests will be
          excepted UNLESS the remote address matches a <code>deny</code>
          pattern.</p>
        </attribute>
  
        <attribute name="deny" required="false">
          <p>A comma-separated list of <em>regular expression</em> patterns
          that the remote client's IP address is compared to.  If this attribute
          is specified, the remote address MUST NOT match for this request to be
          accepted.  If this attribute is not specified, request acceptance is
          governed solely by the <code>accept</code> attribute.</p>
        </attribute>
  
      </attributes>
  
    </subsection>
  
  </section>
  
  
  <section name="Remote Host Filter">
  
    <subsection name="Introduction">
  
      <p>The <strong>Remote Host Filter</strong> allows you to compare the
      hostname of the client that submitted this request against one or more
      <em>regular expressions</em>, and either allow the request to continue
      or refuse to process the request from this client.  A Remote Host
      Filter can be associated with any Catalina container
      (<a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or
      <a href="context.html">Context</a>), and must accept any request
      presented to this container for processing before it will be passed on.</p>
  
    </subsection>
  
    <subsection name="Attributes">
  
      <p>The <strong>Remote Host Filter</strong> supports the following
      configuration attributes:</p>
  
      <attributes>
  
        <attribute name="className" required="true">
          <p>Java class name of the implementation to use.  This MUST be set to
          <strong>org.apache.catalina.valve.RemoteHostValve</strong>.</p>
        </attribute>
  
        <attribute name="accept" required="false">
          <p>A comma-separated list of <em>regular expression</em> patterns
          that the remote client's hostname is compared to.  If this attribute
          is specified, the remote hostname MUST match for this request to be
          accepted.  If this attribute is not specified, all requests will be
          excepted UNLESS the remote hostname matches a <code>deny</code>
          pattern.</p>
        </attribute>
  
        <attribute name="deny" required="false">
          <p>A comma-separated list of <em>regular expression</em> patterns
          that the remote client's hostname is compared to.  If this attribute
          is specified, the remote hostname MUST NOT match for this request to be
          accepted.  If this attribute is not specified, request acceptance is
          governed solely by the <code>accept</code> attribute.</p>
        </attribute>
  
      </attributes>
  
    </subsection>
  
  </section>
  
  
  </body>
  
  
  </document>
  
  
  

Mime
View raw message