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 context.xml host.xml
Date Sat, 25 Aug 2001 03:37:39 GMT
craigmcc    01/08/24 20:37:39

  Added:       webapps/tomcat-docs/config context.xml host.xml
  Log:
  Add new-style docs for the <Host> and <Context> elements:
  
  TODO:  Nested Components (DefaultContext, Loader, Logger, Manager, Realm,
  Resources, Valve) and update the table of contents on the index page.
  
  Revision  Changes    Path
  1.1                  jakarta-tomcat-4.0/webapps/tomcat-docs/config/context.xml
  
  Index: context.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 Context Container</title>
    </properties>
  
  <body>
  
  
  <section name="Introduction">
  
    <p>The <strong>Context</strong> element represents a <em>web
    application</em>, which is run within a particular virtual host.
    Each web application is based on a <em>Web Application Archive</em>
    (WAR) file, or a corresponding directory containing the corresponding
    unpacked contents, as described in the Servlet Specification (version
    2.2 or later).  For more information about web application archives,
    you can download the
    <a href="http://java.sun.com/products/servlet/download.html">Servlet
    Specification</a>, and review the Tomcat
    <a href="../appdev/index.html">Application Developer's Guide</a>.</p>
  
    <p>The web application used to process each HTTP request is selected
    by Catalina based on matching the longest possible prefix of the
    Request URI against the <em>context path</em> of each defined Context.
    Once selected, that Context will select an appropriate servlet to
    process the incoming request, according to the servlet mappings defined
    in the <em>web application deployment descriptor</em> file (which MUST
    be located at <code>/WEB-INF/web.xml</code> within the web app's
    directory hierarchy).</p>
  
    <p>You may define as many <strong>Context</strong> elements as you
    wish, nested within a <a href="host.html">Host</a> element in
    <code>conf/server.xml</code>.  Each such Context MUST have a unique
    context path, which is defined by the <code>path</code> attribute.
    In addition, you MUST define a Context with a context path equal to
    a zero-length string.  This Context becomes the <em>default</em>
    web application for this virtual host, and is used to process all
    requests that do not match any other Context's context path.</p>
  
    <p>In addition to explicitly specified Context elements, there are
    several techniques by which Context elements can be created automatically
    for you.  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.</p>
  
  </section>
  
  
  <section name="Attributes">
  
    <subsection name="Common Attributes">
  
      <p>All implementations of <strong>Host</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.Context</code> interface.
          If not specified, the standard value (defined below) will be used.</p>
        </attribute>
  
        <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="docBase" required="true">
          <p>The <em>Document Base</em> (also known as the <em>Context
          Root</em>) directory for this web application, or the pathname
          to the web application archive file (if this web application is
          being executed directly from the WAR file).    You may specify
          an absolute pathname for this directory or WAR file, or a pathname
          that is relative to the <code>appBase</code> directory of the
          owning <a href="host.html">Host</a>.</p>
        </attribute>
  
        <attribute name="override" required="false">
          <p>Set to <code>true</code> to have explicit settings in this
          Context element override any corresponding settings in the
          <a href="defaultcontext.html">DefaultContext</a> element associated
          with our owning <a href="host.html">Host</a>.  By default, settings
          in the DefaultContext element will be used.</p>
        </attribute>
  
        <attribute name="path" required="true">
          <p>The <em>context path</em> of this web application, which is
          matched against the beginning of each request URI to select the
          appropriate web application for processing.  All of the context paths
          within a particular <a href="host.html">Host</a> must be unique.
          If you specify a context path of an empty string (""), you are
          defining the <em>default</em> web application for this Host, which
          will process all requests not assigned to other Contexts.</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>Context</strong> is
      <strong>org.apache.catalina.core.StandardContext</strong>.
      It supports the following additional attributes (in addition to the
      common attributes listed above):</p>
  
      <attributes>
  
        <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="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>You can nest at most one instance of the following utility components
    by nesting a corresponding element inside your <strong>Context</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 this 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 this <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 this 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 this 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 this web application.  Normally, the
        default configuration of the resource manager will be sufficient.</li>
    </ul>
  
  </section>
  
  
  <section name="Special Features">
  
  
    <subsection name="Access Logs">
  
      <p>When you run a web server, one of the output files normally generated
      is an <em>access log</em>, which generates one line of information for
      each request processed by the server, in a standard format.  Catalina
      includes an optional <a href="valve.html">Valve</a> implementation that
      can create access logs in the same standard format created by web servers,
      or in any number of custom formats.</p>
  
      <p>You can ask Catalina to create an access log for all requests
      processed by an <a href="engine.html">Engine</a>,
      <a href="host.html">Host</a>, or <a href="context.html">Context</a>
      by nesting a <a href="valve.html">Valve</a> element like this:</p>
  
  <source>
  &lt;Context path="/examples" ...&gt;
    ...
    &lt;Valve className="org.apache.catalina.valves.AccessLogValve"
           prefix="localhost_access_log." suffix=".txt"
           pattern="common"/&gt;
    ...
  &lt;/Context&gt;
  </source>
  
      <p>See <a href="valve.html#Access Log Valve">Access Log Valve</a>
      for more information on the configuration attributes that are
      supported.</p>
  
    </subsection>
  
  
    <subsection name="Automatic Context Configuration">
  
      <p>If you use the standard <strong>Context</strong> implementation,
      the following configuration steps occur automtically when Catalina
      is started, or whenever this web application is reloaded.  No special
      configuration is required to enable this feature.</p>
      <ul>
      <li>If you have not declared your own <a href="loader.html">Loader</a>
         element, a standard web application class loader will be configured.
         </li>
      <li>If you have not declared your own <a href="manager.html">Manager</a>
          element, a standard session manager will be configured.</li>
      <li>If you have not declared your own <a href="resources.html">Resources</a>
          element, a standard resources manager will be configured.</li>
      <li>The web application properties listed in <code>conf/web.xml</code>
          will be processed as defaults for this web application.  This is used
          to establish default mappings (such as mapping the <code>*.jsp</code>
          extension to the corresponding JSP servlet), and other standard
          features that apply to all web applications.</li>
      <li>The web application properties listed in the
          <code>/WEB-INF/web.xml</code> resource for this web application
          will be processed (if this resource exists).</li>
      <li>If your web application has specified security constraints that might
          require user authentication, an appropriate Authenticator that
          implements the login method you have selected will be configured.</li>
      </ul>
  
    </subsection>
  
  
    <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;Context path="/examples" ...&gt;
    ...
    &lt;Listener className="com.mycompany.mypackage.MyListener" ... &gt;
    ...
  &lt;/Context&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>
  
  
    <subsection name="Request Filters">
  
      <p>You can ask Catalina to check the IP address, or host name, on every
      incoming request directed to the surrounding
      <a href="engine.html">Engine</a>, <a href="host.html">Host</a>,
or
      <a href="context.htm">Context</a> element.  The remote address or name
      will be checked against a configured list of "accept" and/or "deny"
      filters, which are defined using the Regular Expression syntax supported
      by the <a href="http://jakarta.apache.org/regexp/">Jakarta Regexp</a>
      regular expression library.  Requests that come from locations that are
      not accepted will be rejected with an HTTP "Forbidden" error.
      Example filter declarations:</p>
  
  <source>
  &lt;Context path="/examples" ...&gt;
    ...
    &lt;Valve className="org.apache.catalina.valves.RemoteHostValve"
           allow="*.mycompany.com,www.yourcompany.com"/&gt;
    &lt;Valve className="org.apache.catalina.valves.RemoteAddrValve"
           deny="192.168.1.*"/&gt;
    ...
  &lt;/Context&gt;
  </source>
  
    <p>See <a href="valve.html#Remote Address Filter">Remote Address Filter</a>
    and <a href="valve.html#Remove Host Filter">Remote Host Filter</a> for
    more information about the configuration options that are supported.</p>
  
    </subsection>
  
  
  </section>
  
  
  </body>
  
  
  </document>
  
  
  
  1.1                  jakarta-tomcat-4.0/webapps/tomcat-docs/config/host.xml
  
  Index: host.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 Host Container</title>
    </properties>
  
  <body>
  
  
  <section name="Introduction">
  
    <p>The <strong>Host</strong> element represents a <em>virtual
host</em>,
    which is an association of a network name for a server (such as
    "www.mycompany.com" with the particular server on which Catalina is
    running.  In order to be effective, this name must be registered in the
    <em>Domain Name Service</em> (DNS) server that manages the Internet
    domain you belong to - contact your Network Administrator for more
    information.</p>
  
    <p>In many cases, System Administrators wish to associate more than
    one network name (such as <code>www.mycompany.com</code> and
    <code>company.com</code>) with the same virtual host and applications.
    This can be accomplished using the <a href="#Host Name Aliases">Host
    Name Aliases</a> feature discussed below.</p>
  
    <p>One or more <strong>Host</strong> elements are nested inside an
    <a href="engine.html">Engine</a> element.  Inside the Host element, you
    can nest <a href="context.html">Context</a> elements for the web
    applications associated with this virtual host.  Exactly one of the Hosts
    associated with each Engine MUST have a name matching the
    <code>defaultHost</code> attribute of that Engine.</p>
  
  </section>
  
  
  <section name="Attributes">
  
    <subsection name="Common Attributes">
  
      <p>All implementations of <strong>Host</strong>
      support the following attributes:</p>
  
      <attributes>
  
        <attribute name="appBase" required="true">
          <p>The <em>Application Base</em> directory for this virtual host.
          This is the pathname of a directory that may contain web applications
          to be deployed on this virtual host.  You may specify an
          absolute pathname for this directory, or a pathname that is relative
          to the <code>$CATALINA_HOME</code> directory.  See
          <a href="#Automatic Application Deployment">Automatic Application
          Deployment</a> for more information on automatic recognition and
          deployment of web applications to be deployed automatically.</p>
        </attribute>
  
        <attribute name="className" required="false">
          <p>Java class name of the implementation to use.  This class must
          implement the <code>org.apache.catalina.Host</code> interface.
          If not specified, the standard value (defined below) will be used.</p>
        </attribute>
  
        <attribute name="name" required="true">
          <p>Network name of this virtual host, as registered in your
          <em>Domain Name Service</em> server.  One of the Hosts nested within
          an <a href="engine.html">Engine</a> MUST have a name that matches the
          <code>defaultHost</code> setting for that Engine.  See
          <a href="#Host Name Aliases">Host Name Aliases</a> for information
          on how to assign more than one network name to the same
          virtual host.</p>
        </attribute>
  
      </attributes>
  
    </subsection>
  
  
    <subsection name="Standard Implementation">
  
      <p>The standard implementation of <strong>Host</strong> is
      <strong>org.apache.catalina.core.StandardHost</strong>.
      It supports the following additional attributes (in addition to the
      common attributes listed above):</p>
  
      <attributes>
  
        <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="unpackWARs" required="false">
          <p>Set to <code>true</code> if you want web applications that
are
          deployed into this virtual host from a Web Application Archive (WAR)
          file to be unpacked into a disk directory structure, or
          <code>false</code> to run the application directly from a WAR file.</p>
        </attribute>
  
      </attributes>
  
    </subsection>
  
  
  </section>
  
  
  <section name="Nested Components">
  
    <p>You can nest one or more <a href="host.html">Context</a> elements
inside
    this <strong>Context</strong> element, each representing a different web
    application associated with this virtual host.  In addition, you can nest a
    single <a href="defaultcontext.html">DefaultContext</a> element that defines
    default values for subsequently deployed web applications.</p>
  
    <p>You can nest at most one instance of the following utility components
    by nesting a corresponding element inside your <strong>Host</strong>
    element:</p>
    <ul>
    <li><a href="logger.html"><strong>Logger</strong></a> -
        Configure a logger that will receive
        and process all log messages for this <strong>Host</strong>, plus
        messages from <a href="context.html">Contexts</a> associated with
        this Host (unless overridden by a
        <a href="logger.html">Logger</a> configuration at a lower level).</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 shared across all
        <a href="context.html">Contexts</a> nested inside this Host (unless
        overridden by a <a href="realm.html">Realm</a> configuration
        at a lower level).</li>
    </ul>
  
  </section>
  
  
  <section name="Special Features">
  
  
    <subsection name="Access Logs">
  
      <p>When you run a web server, one of the output files normally generated
      is an <em>access log</em>, which generates one line of information for
      each request processed by the server, in a standard format.  Catalina
      includes an optional <a href="valve.html">Valve</a> implementation that
      can create access logs in the same standard format created by web servers,
      or in any number of custom formats.</p>
  
      <p>You can ask Catalina to create an access log for all requests
      processed by an <a href="engine.html">Engine</a>,
      <a href="host.html">Host</a>, or <a href="context.html">Context</a>
      by nesting a <a href="valve.html">Valve</a> element like this:</p>
  
  <source>
  &lt;Host name="localhost" ...&gt;
    ...
    &lt;Valve className="org.apache.catalina.valves.AccessLogValve"
           prefix="localhost_access_log." suffix=".txt"
           pattern="common"/&gt;
    ...
  &lt;/Host&gt;
  </source>
  
      <p>See <a href="valve.html#Access Log Valve">Access Log Valve</a>
      for more information on the configuration attributes that are
      supported.</p>
  
    </subsection>
  
  
    <subsection name="Automatic Application Deployment">
  
      <p>If you are using the standard <strong>Host</strong> implementation,
      the following actions take place automatically when Catalina is first
      started.  All processing takes place in the <em>application base
      directory</em> that is configured by the <code>appBase</code> property.
      No special configuration is required to enable these activities:</p>
      <ul>
      <li>Any web application archive file that does not have a corresponding
          directory of the same name (without the ".war" extension) will be
          automatically expanded, unless the <code>unpackWARs</code> property
          is set to <code>false</code>.  If you redeploy an updated WAR file,
          be sure to delete the expanded directory when restarting Tomcat, so
          that the updated WAR file will be re-expanded.</li>
      <li>Any subdirectory within the <em>application base directory</em>
          that appears to be an unpacked web application (that is, it contains
          a <code>/WEB-INF/web.xml</code> file) will receive an automatically
          generated <a href="context.html">Context</a> element, even if this
          directory is not mentioned in the <code>conf/server.xml</code> file.
          This generated Context entry will be configured according to the
          properties set in any <a href="defaultcontext.html">DefaultContext</a>
          element nested in this Host element.  The context path for this
          deployed Context will be a slash character ("/") followed by the
          directory name, unless the directory name is ROOT, in which case
          the context path will be an empty string ("").</li>
      </ul>
  
      <p>The net effect of this feature is that you need not specifically
      mention your web applications in <code>conf/server.xml</code>, unless
      you wish to define non-default properties for the corresponding
      <a href="context.html">Context</a>.</p>
  
    </subsection>
  
  
    <subsection name="Host Name Aliases">
  
      <p>In many server environments, Network Administrators have configured
      more than one network name (in the <em>Domain Name Service</em> (DNS)
      server), that resolve to the IP address of the same server.  Normally,
      each such network name would be configured as a separate
      <strong>Host</strong> element in <code>conf/server.xml</code>,
each
      with its own set of web applications.</p>
  
      <p>However, in some circumstances, it is desireable that two or more
      network names should resolve to the <strong>same</strong> virtual host,
      running the same set of applications.  A common use case for this
      scenario is a corporate web site, where it is desireable that users
      be able to utilize either <code>www.mycompany.com</code> or
      <code>company.com</code> to access exactly the same content and
      applications.</p>
  
      <p>This is accomplished by utilizing one or more <strong>Alias</strong>
      elements nested inside your <strong>Host</strong> element.  For
      example:</p>
  <source>
  &lt;Host name="www.mycompany.com" ...&gt;
    ...
    &lt;Alias name="mycompany.com"/&gt;
    ...
  &lt;/Host&gt;
  </source>
  
      <p>In order for this strategy to be effective, all of the network names
      involved must be registered in your DNS server to resolve to the
      same computer that is running this instance of Catalina.</p>
  
    </subsection>
  
  
    <subsection name="Lifecycle Listeners">
  
      <p>If you have implemented a Java object that needs to know when this
      <strong>Host</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;Host name="localhost" ...&gt;
    ...
    &lt;Listener className="com.mycompany.mypackage.MyListener" ... &gt;
    ...
  &lt;/Host&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>
  
  
    <subsection name="Request Filters">
  
      <p>You can ask Catalina to check the IP address, or host name, on every
      incoming request directed to the surrounding
      <a href="engine.html">Engine</a>, <a href="host.html">Host</a>,
or
      <a href="context.htm">Context</a> element.  The remote address or name
      will be checked against a configured list of "accept" and/or "deny"
      filters, which are defined using the Regular Expression syntax supported
      by the <a href="http://jakarta.apache.org/regexp/">Jakarta Regexp</a>
      regular expression library.  Requests that come from locations that are
      not accepted will be rejected with an HTTP "Forbidden" error.
      Example filter declarations:</p>
  
  <source>
  &lt;Host name="localhost" ...&gt;
    ...
    &lt;Valve className="org.apache.catalina.valves.RemoteHostValve"
           allow="*.mycompany.com,www.yourcompany.com"/&gt;
    &lt;Valve className="org.apache.catalina.valves.RemoteAddrValve"
           deny="192.168.1.*"/&gt;
    ...
  &lt;/Host&gt;
  </source>
  
    <p>See <a href="valve.html#Remote Address Filter">Remote Address Filter</a>
    and <a href="valve.html#Remove Host Filter">Remote Host Filter</a> for
    more information about the configuration options that are supported.</p>
  
    </subsection>
  
  
    <subsection name="Single Sign On">
  
      <p>In many environments, but particularly in portal environments, it
      is desireable to have a user challenged to authenticate themselves only
      once over a set of web applications deployed on a particular virtual
      host.  This can be accomplished by nesting an element like this inside
      the Host element for this virtual host:</p>
  
  <source>
  &lt;Host name="localhost" ...&gt;
    ...
    &lt;Valve className="org.apache.catalina.authenticator.SingleSignOn"
           debug="0"/&gt;
    ...
  &lt;/Host&gt;
  </source>
  
      <p>The Single Sign On facility operates according to the following rules:
      </p>
      <ul>
      <li>All web applications configured for this virtual host must share the
          same <a href="realm.html">Realm</a>.  In practice, that means you can
          nest the Realm element inside this Host element (or the surrounding
          <a href="engine.html">Engine</a> element), but not inside a
          <a href="context.html">Context</a> element for one of the involved
          web applications.</li>
      <li>As long as the user accesses only unprotected resources in any of the
          web applications on this virtual host, they will not be challenged
          to authenticate themselves.</li>
      <li>As soon as the user accesses a protected resource in
          <strong>any</strong> web application associated with this virtual
          host, the user will be challenged to authenticate himself or herself,
          using the login method defined for the web application currently
          being accessed.</li>
      <li>Once authenticated, the roles associated with this user will be
          utilized for access control decisions across <strong>all</strong>
          of the associated web applications, without challenging the user
          to authenticate themselves to each application individually.</li>
      <li>As soon as the user logs out of one web application (for example,
          by invalidating or timing out the corresponding session if form
          based login is used), the user's sessions in <strong>all</strong>
          web applications will be invalidated.  Any subsequent attempt to
          access a protected resource in any application will require the
          user to authenticate himself or herself again.</li>
      <li>The Single Sign On feature utilizes HTTP cookies to transmit a token
          that associates each request with the saved user identity, so it can
          only be utilized in client environments that support cookies.</li>
      </ul>
  
    </subsection>
  
  
    <subsection name="User Web Applications">
  
      <p>Many web servers can automatically map a request URI starting with
      a tilde character ("~") and a username to a directory (commonly named
      <code>public_html</code>) in that user's home directory on the server.
      You can accomplish the same thing in Catalina by using a special
      <strong>Listener</strong> element like this (on a Unix system that
      uses the <code>/etc/passwd</code> file to identify valid users):</p>
  
  <source>
  &lt;Host name="localhost" ...&gt;
    ...
    &lt;Listener className="org.apache.catalina.startup.UserConfig"
              directoryName="public_html"
              userClass="org.apache.catalina.startup.PasswdUserDatabase"/&gt;
    ...
  &lt;/Host&gt;
  </source>
  
      <p>On a server where <code>/etc/passwd</code> is not in use, you can
      request Catalina to consider all directories found in a specified base
      directory (such as <code>c:\Homes</code> in this example) to be
      considered "user home" directories for the purposes of this directive:</p>
  
  <source>
  &lt;Host name="localhost" ...&gt;
    ...
    &lt;Listener className="org.apache.catalina.startup.UserConfig"
              directoryName="public_html"
              homeBase=c:\Homes"
              userClass="org.apache.catalina.startup.HomesUserDatabase"/&gt;
    ...
  &lt;/Host&gt;
  </source>
  
      <p>If a user home directory has been set up for a user named
      <code>craigmcc</code>, then its contents will be visible from a
      client browser by making a request to a URL like:</p>
  
  <source>
  http://www.mycompany.com:8080/~craigmcc
  </source>
  
      <p>Successful use of this feature requires recognition of the following
      considerations:</p>
      <ul>
      <li>Each user web application will be deployed with characteristics
          established by any <a href="defaultcontext.html">DefaultContext</a>
          element you have configured for this Host.</li>
      <li>It is legal to include more than one instance of this Listener
          element.  This would only be useful, however, in circumstances
          where you wanted to configure more than one "homeBase" directory.</li>
      <li>The operating system username under which Catalina is executed
          MUST have read access to each user's web application directory,
          and all of its contents.</li>
      </ul>
  
    </subsection>
  
  
  </section>
  
  
  </body>
  
  
  </document>
  
  
  

Mime
View raw message