http://git-wip-us.apache.org/repos/asf/flex-blazeds/blob/5be16a28/attic/servers/apache-tomcat-6.0.29/webapps/docs/config/loader.html ---------------------------------------------------------------------- diff --git a/attic/servers/apache-tomcat-6.0.29/webapps/docs/config/loader.html b/attic/servers/apache-tomcat-6.0.29/webapps/docs/config/loader.html new file mode 100644 index 0000000..aa64f76 --- /dev/null +++ b/attic/servers/apache-tomcat-6.0.29/webapps/docs/config/loader.html @@ -0,0 +1,113 @@ +<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat Configuration Reference - The Loader Component</title><meta content="Craig R. McClanahan" name="author"><style media="print" type="text/css"> + .noPrint {display: none;} + td#mainBody {width: 100%;} + </style></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/";><img border="0" alt=" + The Apache Tomcat Servlet/JSP Container + " align="right" src="../images/tomcat.gif"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 6.0</font></h1></td><td><!--APACHE LOGO--><a href="http://www.apache.org/";><img border="0" alt="Apache Logo" align="right" src="../images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><tr><!--LEFT SIDE NAVIGATION--><td class="noPrint" nowrap valign="top" width="20%"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Config Ref. Home</a></li></ul><p><strong>Top Level Elements</strong></p><ul><li><a href="server.html">Server</a></li><li><a href="service.html">Service</a></li></ul><p><strong>Executors</strong></p><ul><li><a href="executor.html">Executor</a></li></ul><p><strong>Connectors</strong></p><ul><li><a href="http.html">HTTP</a></li><li><a href="ajp.html">AJP</a></li></ul><p><strong>Containers</strong></p> <ul><li><a href="context.html">Context</a></li><li><a href="engine.html">Engine</a></li><li><a href="host.html">Host</a></li><li><a href="cluster.html">Cluster</a></li></ul><p><strong>Nested Components</strong></p><ul><li><a href="listeners.html">Listeners</a></li><li><a href="globalresources.html">Global Resources</a></li><li><a href="loader.html">Loader</a></li><li><a href="manager.html">Manager</a></li><li><a href="realm.html">Realm</a></li><li><a href="resources.html">Resources</a></li><li><a href="valve.html">Valve</a></li></ul><p><strong>Cluster Elements</strong></p><ul><li><a href="cluster.html">Cluster</a></li><li><a href="cluster-manager.html">Manager</a></li><li><a href="cluster-channel.html">Channel</a></li><li><a href="cluster-membership.html">Channel/Membership</a></li><li><a href="cluster-sender.html">Channel/Sender</a></li><li><a href="cluster-receiver.html">Channel/Receiver</a></li><li><a href="cluster-interceptor.html">Channel/Interceptor</a></li><li><a href="cluste r-valve.html">Valve</a></li><li><a href="cluster-deployer.html">Deployer</a></li><li><a href="cluster-listener.html">ClusterListener</a></li></ul><p><strong>Global Settings</strong></p><ul><li><a href="systemprops.html">System properties</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td id="mainBody" align="left" valign="top" width="80%"><h1>Apache Tomcat Configuration Reference</h1><h2>The Loader Component</h2><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote> +<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Attributes">Attributes</a><ol><li><a href="#Common_Attributes">Common Attributes</a></li><li><a href="#Standard_Implementation">Standard Implementation</a></li></ol></li><li><a href="#Nested_Components">Nested Components</a></li><li><a href="#Special_Features">Special Features</a><ol><li><a href="#Logging">Logging</a></li></ol></li></ul> +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote> + + <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 <a href="../class-loader-howto.html">the ClassLoader HowTo</a>.</p> + + <blockquote><em> + <p>The description below uses the variable name $CATALINA_BASE to refer the + base directory against which most relative paths are resolved. If you have + not configured Tomcat 6 for multiple instances by setting a CATALINA_BASE + directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME, + the directory into which you have installed Tomcat 6.</p> + </em></blockquote> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote> + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Common Attributes"><!--()--></a><a name="Common_Attributes"><strong>Common Attributes</strong></a></font></td></tr><tr><td><blockquote> + + <p>All implementations of <strong>Loader</strong> + support the following attributes:</p> + + <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><code>className</code></td><td valign="center" align="left"> + <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> + </td></tr><tr><td valign="center" align="left"><code>delegate</code></td><td valign="center" align="left"> + <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> + </td></tr><tr><td valign="center" align="left"><code>reloadable</code></td><td valign="center" align="left"> + <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> + </td></tr></table> + + </blockquote></td></tr></table> + + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Standard Implementation"><!--()--></a><a name="Standard_Implementation"><strong>Standard Implementation</strong></a></font></td></tr><tr><td><blockquote> + + <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> + + <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><code>loaderClass</code></td><td valign="center" align="left"> + <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>. Custom + <strong>loaderClass</strong> implementations must extend + <code>org.apache.catalina.loader.WebappClassLoader</code>.</p> + </td></tr><tr><td valign="center" align="left"><code>searchExternalFirst</code></td><td valign="center" align="left"> + <p>Set to <code>true</code> if you want repositories outside + of <code>WEB-INF/classes</code> and <code>WEB-INF/lib</code> to + be searched first. Default value is <code>false</code>.</p> + </td></tr></table> + + </blockquote></td></tr></table> + + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Nested Components"><!--()--></a><a name="Nested_Components"><strong>Nested Components</strong></a></font></td></tr><tr><td><blockquote> + + <p>No components may be nested inside a <strong>Loader</strong> element.</p> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Special Features"><!--()--></a><a name="Special_Features"><strong>Special Features</strong></a></font></td></tr><tr><td><blockquote> + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Logging"><strong>Logging</strong></a></font></td></tr><tr><td><blockquote> + + <p>A loader is associated with the log category based on its classname.</p> + + </blockquote></td></tr></table> + +</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em> + Copyright © 1999-2010, Apache Software Foundation + </em></font></div></td></tr></table></body></html> \ No newline at end of file
http://git-wip-us.apache.org/repos/asf/flex-blazeds/blob/5be16a28/attic/servers/apache-tomcat-6.0.29/webapps/docs/config/manager.html ---------------------------------------------------------------------- diff --git a/attic/servers/apache-tomcat-6.0.29/webapps/docs/config/manager.html b/attic/servers/apache-tomcat-6.0.29/webapps/docs/config/manager.html new file mode 100644 index 0000000..d7b204a --- /dev/null +++ b/attic/servers/apache-tomcat-6.0.29/webapps/docs/config/manager.html @@ -0,0 +1,360 @@ +<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat Configuration Reference - The Manager Component</title><meta content="Craig R. McClanahan" name="author"><meta content="Yoav Shapira" name="author"><style media="print" type="text/css"> + .noPrint {display: none;} + td#mainBody {width: 100%;} + </style></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/";><img border="0" alt=" + The Apache Tomcat Servlet/JSP Container + " align="right" src="../images/tomcat.gif"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 6.0</font></h1></td><td><!--APACHE LOGO--><a href="http://www.apache.org/";><img border="0" alt="Apache Logo" align="right" src="../images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><tr><!--LEFT SIDE NAVIGATION--><td class="noPrint" nowrap valign="top" width="20%"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Config Ref. Home</a></li></ul><p><strong>Top Level Elements</strong></p><ul><li><a href="server.html">Server</a></li><li><a href="service.html">Service</a></li></ul><p><strong>Executors</strong></p><ul><li><a href="executor.html">Executor</a></li></ul><p><strong>Connectors</strong></p><ul><li><a href="http.html">HTTP</a></li><li><a href="ajp.html">AJP</a></li></ul><p><strong>Containers</strong></p> <ul><li><a href="context.html">Context</a></li><li><a href="engine.html">Engine</a></li><li><a href="host.html">Host</a></li><li><a href="cluster.html">Cluster</a></li></ul><p><strong>Nested Components</strong></p><ul><li><a href="listeners.html">Listeners</a></li><li><a href="globalresources.html">Global Resources</a></li><li><a href="loader.html">Loader</a></li><li><a href="manager.html">Manager</a></li><li><a href="realm.html">Realm</a></li><li><a href="resources.html">Resources</a></li><li><a href="valve.html">Valve</a></li></ul><p><strong>Cluster Elements</strong></p><ul><li><a href="cluster.html">Cluster</a></li><li><a href="cluster-manager.html">Manager</a></li><li><a href="cluster-channel.html">Channel</a></li><li><a href="cluster-membership.html">Channel/Membership</a></li><li><a href="cluster-sender.html">Channel/Sender</a></li><li><a href="cluster-receiver.html">Channel/Receiver</a></li><li><a href="cluster-interceptor.html">Channel/Interceptor</a></li><li><a href="cluste r-valve.html">Valve</a></li><li><a href="cluster-deployer.html">Deployer</a></li><li><a href="cluster-listener.html">ClusterListener</a></li></ul><p><strong>Global Settings</strong></p><ul><li><a href="systemprops.html">System properties</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td id="mainBody" align="left" valign="top" width="80%"><h1>Apache Tomcat Configuration Reference</h1><h2>The Manager Component</h2><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote> +<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Attributes">Attributes</a><ol><li><a href="#Common_Attributes">Common Attributes</a></li><li><a href="#Standard_Implementation">Standard Implementation</a></li></ol></li><li><a href="#Nested_Components">Nested Components</a></li><li><a href="#Special_Features">Special Features</a><ol><li><a href="#Restart_Persistence">Restart Persistence</a></li></ol></li></ul> +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote> + + <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> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote> + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Common Attributes"><!--()--></a><a name="Common_Attributes"><strong>Common Attributes</strong></a></font></td></tr><tr><td><blockquote> + + <p>All implementations of <strong>Manager</strong> + support the following attributes:</p> + + <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><code>className</code></td><td valign="center" align="left"> + <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> + </td></tr><tr><td valign="center" align="left"><code>distributable</code></td><td valign="center" align="left"> + <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><distributable></code> element in the web application + deployment descriptor (<code>/WEB-INF/web.xml</code>).</p> + </td></tr></table> + + </blockquote></td></tr></table> + + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Standard Implementation"><!--()--></a><a name="Standard_Implementation"><strong>Standard Implementation</strong></a></font></td></tr><tr><td><blockquote> + + <p>Tomcat provides two standard implementations of <strong>Manager</strong> + for use - the default one stores active sessions, while the optional one + stores active sessions that have been swapped out (in addition to saving + sessions across a restart of Tomcat) in a storage location that is selected + via the use of an appropriate <strong>Store</strong> nested element.</p> + + <h3>Standard Manager Implementation</h3> + + <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> + + <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><code>algorithm</code></td><td valign="center" align="left"> + <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> + </td></tr><tr><td valign="center" align="left"><code>entropy</code></td><td valign="center" align="left"> + <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> + </td></tr><tr><td valign="center" align="left"><code>maxActiveSessions</code></td><td valign="center" align="left"> + <p>The maximum number of active sessions that will be created by + this Manager, or -1 (the default) for no limit.</p> + </td></tr><tr><td valign="center" align="left"><code>maxInactiveInterval</code></td><td valign="center" align="left"> + <p>The initial maximum time interval, in seconds, + between client requests before a session is invalidated. A negative value + will result in sessions never timing out. If the attribute is not provided, + a default of 60 seconds is used.</p> + + <p>This attribute provides the initial value whenever a + new session is created, but the interval may be dynamically + varied by a servlet via the + <code>setMaxInactiveInterval</code> method of the <code>HttpSession</code> object.</p> + </td></tr><tr><td valign="center" align="left"><code>pathname</code></td><td valign="center" align="left"> + <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. Restart persistence may be + disabled by setting this attribute to an empty string.</p> + </td></tr><tr><td valign="center" align="left"><code>processExpiresFrequency</code></td><td valign="center" align="left"> + <p>Frequency of the session expiration, and related manager operations. + Manager operations will be done once for the specified amount of + backgrondProcess calls (i.e., the lower the amount, the more often the + checks will occur). The minimum value is 1, and the default value is 6. + </p> + </td></tr><tr><td valign="center" align="left"><code>randomClass</code></td><td valign="center" align="left"> + <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> + </td></tr><tr><td valign="center" align="left"><code>sessionIdLength</code></td><td valign="center" align="left"> + <p>The length of session ids created by this Manager, excluding any + JVM route information used for load balancing. + The default is 16.</p> + </td></tr></table> + + <h3>Persistent Manager Implementation</h3> + + <p><em><strong>WARNING - Use of this Manager implementation + has not been thoroughly tested, and should be considered experimental! + </strong></em></p> + + <p><strong>NOTE:</strong> You must set either the + <code>org.apache.catalina.session.StandardSession.ACTIVITY_CHECK</code> or + <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> + <a href="systemprops.html">system properties</a> to <code>true</code> for + the persistent manager to work correctly.</p> + + <p>The persistent implementation of <strong>Manager</strong> is + <strong>org.apache.catalina.session.PersistentManager</strong>. In + addition to the usual operations of creating and deleting sessions, a + <code>PersistentManager</code> has the capability to swap active (but + idle) sessions out to a persistent storage mechanism, as well as to save + all sessions across a normal restart of Tomcat. The actual persistent + storage mechanism used is selected by your choice of a + <strong>Store</strong> element nested inside the <strong>Manager</strong> + element - this is required for use of <code>PersistentManager</code>.</p> + + <p>This implementation of Manager supports the following attributes in + addition to the <a href="#Common Attributes">Common Attributes</a> + described earlier.</p> + + <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><code>algorithm</code></td><td valign="center" align="left"> + <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> + </td></tr><tr><td valign="center" align="left"><code>className</code></td><td valign="center" align="left"> + <p>Java class name of the implementation to use. This class must + implement the <code>org.apache.catalina.Manager</code> interface. + You <strong>must</strong> specify + <code>org.apache.catalina.session.PersistentManager</code> to use + this manager implementation.</p> + </td></tr><tr><td valign="center" align="left"><code>entropy</code></td><td valign="center" align="left"> + <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> + </td></tr><tr><td valign="center" align="left"><code>maxActiveSessions</code></td><td valign="center" align="left"> + <p>The maximum number of active sessions that will be created by + this Manager, or -1 (the default) for no limit.</p> + </td></tr><tr><td valign="center" align="left"><code>maxIdleBackup</code></td><td valign="center" align="left"> + <p>The time interval (in seconds) since the last access to a session + before it is eligible for being persisted to the session store, or + <code>-1</code> to disable this feature. By default, this feature is + disabled.</p> + </td></tr><tr><td valign="center" align="left"><code>maxIdleSwap</code></td><td valign="center" align="left"> + <p>The time interval (in seconds) since the last access to a session + before it should be persisted to the session store, and + passivated out of the server's memory, or <code>-1</code> to disable + this feature. If this feature is enabled, the time interval specified + here should be equal to or longer than the value specified for + <code>maxIdleBackup</code>. By default, this feature is disabled.</p> + </td></tr><tr><td valign="center" align="left"><code>minIdleSwap</code></td><td valign="center" align="left"> + <p>The time interval (in seconds) since the last access to a session + before it will be eligible to be persisted to the session store, and + passivated out of the server's memory, or <code>-1</code> for this + swapping to be available at any time. If specified, this value should + be less than that specified by <code>maxIdleSwap</code>. By default, + this value is set to <code>-1</code>.</p> + </td></tr><tr><td valign="center" align="left"><code>maxInactiveInterval</code></td><td valign="center" align="left"> + <p>The initial maximum time interval, in seconds, + between client requests before a session is invalidated. A negative value + will result in sessions never timing out. If the attribute is not provided, + a default of 60 seconds is used.</p> + + <p>This attribute provides the initial value whenever a + new session is created, but the interval may be dynamically + varied by a servlet via the + <code>setMaxInactiveInterval</code>method of the <code>HttpSession</code> object.</p> + </td></tr><tr><td valign="center" align="left"><code>randomClass</code></td><td valign="center" align="left"> + <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> + </td></tr><tr><td valign="center" align="left"><code>saveOnRestart</code></td><td valign="center" align="left"> + <p>Should all sessions be persisted and reloaded when Tomcat is shut + down and restarted (or when this application is reloaded)? By default, + this attribute is set to <code>true</code>.</p> + </td></tr><tr><td valign="center" align="left"><code>sessionIdLength</code></td><td valign="center" align="left"> + <p>The length of session ids created by this Manager, excluding any + JVM route information used for load balancing. + The default is 16.</p> + </td></tr></table> + + <p>In order to successfully use a PersistentManager, you must nest inside + it a <strong><Store></strong> element, as described below.</p> + + </blockquote></td></tr></table> + + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Nested Components"><!--()--></a><a name="Nested_Components"><strong>Nested Components</strong></a></font></td></tr><tr><td><blockquote> + + <h3>Standard Manager Implementation</h3> + + <p>If you are using the <em>Standard Manager Implementation</em> + as described above, no elements may be nested inside your + <strong><Manager></strong> element.</p> + + <h3>Persistent Manager Implementation</h3> + + <p>If you are using the <em>Persistent Manager Implementation</em> + as described above, you <strong>MUST</strong> nest a + <strong><Store></strong> element inside, which defines the + characteristics of the persistent data storage. Two implementations + of the <code><Store></code> element are currently available, + with different characteristics, as described below.</p> + + <h5>File Based Store</h5> + + <p>The <em>File Based Store</em> implementation saves swapped out + sessions in individual files (named based on the session identifier) + in a configurable directory. Therefore, you are likely to encounter + scalability problems as the number of active sessions increases, and + this should primarily be considered a means to easily experiment.</p> + + <p>To configure this, add a <code><Store></code> nested inside + your <code><Manager></code> element with the following attributes: + </p> + + <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><code>checkInterval</code></td><td valign="center" align="left"> + <p>The interval (in seconds) between checks for expired sessions + among those sessions that are currently swapped out. By default, + this interval is set to 60 seconds (one minute).</p> + </td></tr><tr><td valign="center" align="left"><strong><code>className</code></strong></td><td valign="center" align="left"> + <p>Java class name of the implementation to use. This class must + implement the <code>org.apache.catalina.Store</code> interface. You + <strong>must</strong> specify + <code>org.apache.catalina.session.FileStore</code> + to use this implementation.</p> + </td></tr><tr><td valign="center" align="left"><code>directory</code></td><td valign="center" align="left"> + <p>Absolute or relative (to the temporary work directory for this web + application) pathname of the directory into which individual session + files are written. If not specified, the temporary work directory + assigned by the container is utilized.</p> + </td></tr></table> + + + <h5>JDBC Based Store</h5> + + <p>The <em>JDBC Based Store</em> implementation saves swapped out + sessions in individual rows of a preconfigured table in a database + that is accessed via a JDBC driver. With large numbers of swapped out + sessions, this implementation will exhibit improved performance over + the File Based Store described above.</p> + + <p>To configure this, add a <code><Store></code> nested inside + your <code><Manager></code> element with the following attributes: + </p> + + <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><code>checkInterval</code></td><td valign="center" align="left"> + <p>The interval (in seconds) between checks for expired sessions + among those sessions that are currently swapped out. By default, + this interval is set to 60 seconds (one minute).</p> + </td></tr><tr><td valign="center" align="left"><strong><code>className</code></strong></td><td valign="center" align="left"> + <p>Java class name of the implementation to use. This class must + implement the <code>org.apache.catalina.Store</code> interface. You + <strong>must</strong> specify + <code>org.apache.catalina.session.JDBCStore</code> + to use this implementation.</p> + </td></tr><tr><td valign="center" align="left"><strong><code>connectionURL</code></strong></td><td valign="center" align="left"> + <p>The connection URL that will be handed to the configured JDBC + driver to establish a connection to the database containing our + session table.</p> + </td></tr><tr><td valign="center" align="left"><strong><code>driverName</code></strong></td><td valign="center" align="left"> + <p>Java class name of the JDBC driver to be used.</p> + </td></tr><tr><td valign="center" align="left"><strong><code>sessionAppCol</code></strong></td><td valign="center" align="left"> + <p>Name of the database column, contained in the specified session + table, that contains the Engine, Host, and Web Application Context + name in the format <code>/Engine/Host/Context</code>.</p> + </td></tr><tr><td valign="center" align="left"><strong><code>sessionDataCol</code></strong></td><td valign="center" align="left"> + <p>Name of the database column, contained in the specified + session table, that contains the serialized form of all session + attributes for a swapped out session. The column type must accept + a binary object (typically called a BLOB).</p> + </td></tr><tr><td valign="center" align="left"><strong><code>sessionIdCol</code></strong></td><td valign="center" align="left"> + <p>Name of the database column, contained in the specified + session table, that contains the session identifier of the + swapped out session. The column type must accept character + string data of at least as many characters as are contained + in session identifiers created by Tomcat (typically 32).</p> + </td></tr><tr><td valign="center" align="left"><strong><code>sessionLastAccessedCol</code></strong></td><td valign="center" align="left"> + <p>Name of the database column, contained in the specified + session table, that contains the <code>lastAccessedTime</code> + property of this session. The column type must accept a + Java <code>long</code> (64 bits).</p> + </td></tr><tr><td valign="center" align="left"><strong><code>sessionMaxInactiveCol</code></strong></td><td valign="center" align="left"> + <p>Name of the database column, contained in the specified + session table, that contains the <code>maxInactiveInterval</code> + property of this session. The column type must accept a + Java <code>integer</code> (32 bits).</p> + </td></tr><tr><td valign="center" align="left"><strong><code>sessionTable</code></strong></td><td valign="center" align="left"> + <p>Name of the database table to be used for storing swapped out + sessions. This table must contain (at least) the database columns + that are configured by the other attributes of this element.</p> + </td></tr><tr><td valign="center" align="left"><strong><code>sessionValidCol</code></strong></td><td valign="center" align="left"> + <p>Name of the database column, contained in the specified + session table, that contains a flag indicating whether this + swapped out session is still valid or not. The column type + must accept a single character.</p> + </td></tr></table> + + <p>Before attempting to use the JDBC Based Store for the first time, + you must create the table that will be used to store swapped out sessions. + Detailed SQL commands vary depending on the database you are using, but + a script like this will generally be required:</p> + +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +create table tomcat_sessions ( + session_id varchar(100) not null primary key, + valid_session char(1) not null, + max_inactive int not null, + last_access bigint not null, + app_name varchar(255), + session_data mediumblob, + KEY kapp_name(app_name) +); +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="../images/void.gif"></td></tr></table></div> + + <p>In order for the JDBC Based Store to successfully connect to your + database, the JDBC driver you configure must be visible to Tomcat's + internal class loader. Generally, that means you must place the JAR + file containing this driver into the <code>$CATALINA_HOME/lib</code> + directory.</p> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Special Features"><!--()--></a><a name="Special_Features"><strong>Special Features</strong></a></font></td></tr><tr><td><blockquote> + + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Restart Persistence"><!--()--></a><a name="Restart_Persistence"><strong>Restart Persistence</strong></a></font></td></tr><tr><td><blockquote> + + <p>Whenever 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><distributable></code> element in your web + application deployment descriptor (<code>/WEB-INF/web.xml</code>).</p> + + </blockquote></td></tr></table> + +</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em> + Copyright © 1999-2010, Apache Software Foundation + </em></font></div></td></tr></table></body></html> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/flex-blazeds/blob/5be16a28/attic/servers/apache-tomcat-6.0.29/webapps/docs/config/realm.html ---------------------------------------------------------------------- diff --git a/attic/servers/apache-tomcat-6.0.29/webapps/docs/config/realm.html b/attic/servers/apache-tomcat-6.0.29/webapps/docs/config/realm.html new file mode 100644 index 0000000..b5243db --- /dev/null +++ b/attic/servers/apache-tomcat-6.0.29/webapps/docs/config/realm.html @@ -0,0 +1,574 @@ +<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat Configuration Reference - The Realm Component</title><meta content="Craig R. McClanahan" name="author"><style media="print" type="text/css"> + .noPrint {display: none;} + td#mainBody {width: 100%;} + </style></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/";><img border="0" alt=" + The Apache Tomcat Servlet/JSP Container + " align="right" src="../images/tomcat.gif"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 6.0</font></h1></td><td><!--APACHE LOGO--><a href="http://www.apache.org/";><img border="0" alt="Apache Logo" align="right" src="../images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><tr><!--LEFT SIDE NAVIGATION--><td class="noPrint" nowrap valign="top" width="20%"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Config Ref. Home</a></li></ul><p><strong>Top Level Elements</strong></p><ul><li><a href="server.html">Server</a></li><li><a href="service.html">Service</a></li></ul><p><strong>Executors</strong></p><ul><li><a href="executor.html">Executor</a></li></ul><p><strong>Connectors</strong></p><ul><li><a href="http.html">HTTP</a></li><li><a href="ajp.html">AJP</a></li></ul><p><strong>Containers</strong></p> <ul><li><a href="context.html">Context</a></li><li><a href="engine.html">Engine</a></li><li><a href="host.html">Host</a></li><li><a href="cluster.html">Cluster</a></li></ul><p><strong>Nested Components</strong></p><ul><li><a href="listeners.html">Listeners</a></li><li><a href="globalresources.html">Global Resources</a></li><li><a href="loader.html">Loader</a></li><li><a href="manager.html">Manager</a></li><li><a href="realm.html">Realm</a></li><li><a href="resources.html">Resources</a></li><li><a href="valve.html">Valve</a></li></ul><p><strong>Cluster Elements</strong></p><ul><li><a href="cluster.html">Cluster</a></li><li><a href="cluster-manager.html">Manager</a></li><li><a href="cluster-channel.html">Channel</a></li><li><a href="cluster-membership.html">Channel/Membership</a></li><li><a href="cluster-sender.html">Channel/Sender</a></li><li><a href="cluster-receiver.html">Channel/Receiver</a></li><li><a href="cluster-interceptor.html">Channel/Interceptor</a></li><li><a href="cluste r-valve.html">Valve</a></li><li><a href="cluster-deployer.html">Deployer</a></li><li><a href="cluster-listener.html">ClusterListener</a></li></ul><p><strong>Global Settings</strong></p><ul><li><a href="systemprops.html">System properties</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td id="mainBody" align="left" valign="top" width="80%"><h1>Apache Tomcat Configuration Reference</h1><h2>The Realm Component</h2><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote> +<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Attributes">Attributes</a><ol><li><a href="#Common_Attributes">Common Attributes</a></li><li><a href="#Standard_Implementation">Standard Implementation</a></li></ol></li><li><a href="#Nested_Components">Nested Components</a></li><li><a href="#Special_Features">Special Features</a></li></ul> +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote> + + <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, as well as more information on configuring and using the + standard realm component implementations, please see the + <a href="../realm-howto.html">Container-Managed Security Guide</a>. + </p> + + <blockquote><em> + <p>The description below uses the variable name $CATALINA_BASE to refer the + base directory against which most relative paths are resolved. If you have + not configured Tomcat 6 for multiple instances by setting a CATALINA_BASE + directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME, + the directory into which you have installed Tomcat 6.</p> + </em></blockquote> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote> + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Common Attributes"><!--()--></a><a name="Common_Attributes"><strong>Common Attributes</strong></a></font></td></tr><tr><td><blockquote> + + <p>All implementations of <strong>Realm</strong> + support the following attributes:</p> + + <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><strong><code>className</code></strong></td><td valign="center" align="left"> + <p>Java class name of the implementation to use. This class must + implement the <code>org.apache.catalina.Realm</code> interface.</p> + </td></tr></table> + + </blockquote></td></tr></table> + + + <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Standard Implementation"><!--()--></a><a name="Standard_Implementation"><strong>Standard Implementation</strong></a></font></td></tr><tr><td><blockquote> + + <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> + + <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><strong><code>connectionName</code></strong></td><td valign="center" align="left"> + <p>The database username to use when establishing the JDBC + connection.</p> + </td></tr><tr><td valign="center" align="left"><strong><code>connectionPassword</code></strong></td><td valign="center" align="left"> + <p>The database password to use when establishing the JDBC + connection.</p> + </td></tr><tr><td valign="center" align="left"><strong><code>connectionURL</code></strong></td><td valign="center" align="left"> + <p>The connection URL to be passed to the JDBC driver when + establishing a database connection.</p> + </td></tr><tr><td valign="center" align="left"><code>digest</code></td><td valign="center" align="left"> + <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> + </td></tr><tr><td valign="center" align="left"><code>digestEncoding</code></td><td valign="center" align="left"> + <p>The charset for encoding digests. If not specified, the platform + default will be used.</p> + </td></tr><tr><td valign="center" align="left"><strong><code>driverName</code></strong></td><td valign="center" align="left"> + <p>Fully qualified Java class name of the JDBC driver to be + used to connect to the authentication database.</p> + </td></tr><tr><td valign="center" align="left"><strong><code>roleNameCol</code></strong></td><td valign="center" align="left"> + <p>Name of the column, in the "user roles" table, which contains + a role name assigned to the corresponding user.</p> + </td></tr><tr><td valign="center" align="left"><strong><code>userCredCol</code></strong></td><td valign="center" align="left"> + <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> + </td></tr><tr><td valign="center" align="left"><strong><code>userNameCol</code></strong></td><td valign="center" align="left"> + <p>Name of the column, in the "users" and "user roles" table, + that contains the user's username.</p> + </td></tr><tr><td valign="center" align="left"><strong><code>userRoleTable</code></strong></td><td valign="center" align="left"> + <p>Name of the "user roles" table, which must contain columns + named by the <code>userNameCol</code> and <code>roleNameCol</code> + attributes.</p> + </td></tr><tr><td valign="center" align="left"><strong><code>userTable</code></strong></td><td valign="center" align="left"> + <p>Name of the "users" table, which must contain columns named + by the <code>userNameCol</code> and <code>userCredCol</code> + attributes.</p> + </td></tr></table> + + <p>See the <a href="../realm-howto.html">Container-Managed Security Guide</a> for more + information on setting up container managed security using the + JDBC Database Realm component.</p> + + + <h3> + DataSource Database Realm (org.apache.catalina.realm.DataSourceRealm) + </h3> + + <p>The <strong>DataSource Database Realm</strong> connects Catalina to + a relational database, accessed through a JNDI named JDBC DataSource + 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>The JDBC Realm uses a single db connection. This requires that + realm based authentication be synchronized, i.e. only one authentication + can be done at a time. This could be a bottleneck for applications + with high volumes of realm based authentications.</p> + + <p>The DataSource Database Realm supports simultaneous realm based + authentications and allows the underlying JDBC DataSource to + handle optimizations like database connection pooling.</p> + + <p>A rich set of additional attributes lets you configure the name + of the JNDI JDBC DataSource, as well as the table and + column names used to retrieve the required information:</p> + + <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><strong><code>dataSourceName</code></strong></td><td valign="center" align="left"> + <p>The name of the JNDI JDBC DataSource for this Realm.</p> + </td></tr><tr><td valign="center" align="left"><code>digest</code></td><td valign="center" align="left"> + <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> + </td></tr><tr><td valign="center" align="left"><code>localDataSource</code></td><td valign="center" align="left"> + <p>When the realm is nested inside a Context element, this allows the + realm to use a DataSource defined for the Context rather than a global + DataSource. If not specified, the default is <code>false</code>: use a + global DataSource.</p> + </td></tr><tr><td valign="center" align="left"><strong><code>roleNameCol</code></strong></td><td valign="center" align="left"> + <p>Name of the column, in the "user roles" table, which contains + a role name assigned to the corresponding user.</p> + </td></tr><tr><td valign="center" align="left"><strong><code>userCredCol</code></strong></td><td valign="center" align="left"> + <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> + </td></tr><tr><td valign="center" align="left"><strong><code>userNameCol</code></strong></td><td valign="center" align="left"> + <p>Name of the column, in the "users" and "user roles" table, + that contains the user's username.</p> + </td></tr><tr><td valign="center" align="left"><strong><code>userRoleTable</code></strong></td><td valign="center" align="left"> + <p>Name of the "user roles" table, which must contain columns + named by the <code>userNameCol</code> and <code>roleNameCol</code> + attributes.</p> + </td></tr><tr><td valign="center" align="left"><strong><code>userTable</code></strong></td><td valign="center" align="left"> + <p>Name of the "users" table, which must contain columns named + by the <code>userNameCol</code> and <code>userCredCol</code> + attributes.</p> + </td></tr></table> + + <p>See the <a href="../realm-howto.html#DataSourceRealm"> + DataSource Realm HOW-TO</a> for more information on setting up container + managed security using the DataSource 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, + that stores usernames, passwords, and their associated + roles. Changes to the directory are immediately reflected in the + information used to authenticate new logins.</p> + + + <p>The directory realm supports a variety of approaches to using + LDAP for authentication:</p> + + <ul> + <li>The realm can either use a pattern to determine the + distinguished name (DN) of the user's directory entry, or search + the directory to locate that entry. + </li> + + <li>The realm can authenticate the user either by binding to the + directory with the DN of the user's entry and the password + presented by the user, or by retrieving the password from the + user's entry and performing a comparison locally. + </li> + + <li>Roles may be represented in the directory as explicit entries + found by a directory search (e.g. group entries of which the user + is a member), as the values of an attribute in the user's entry, + or both. + </li> + </ul> + + <p> A rich set of additional attributes lets you configure the + required behaviour as well as the connection to the underlying + directory and the element and attribute names used to retrieve + information from the directory:</p> + + <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><code>adCompat</code></td><td valign="center" align="left"> + <p>Microsoft Active Directory often returns referrals. + When iterating over NamingEnumerations these lead to + PartialResultExceptions. If you want us to ignore those exceptions, + set this attribute to "true". Unfortunately there's no stable way + to detect, if the Exceptions really come from an AD referral. + The default value is "false".</p> + </td></tr><tr><td valign="center" align="left"><code>alternateURL</code></td><td valign="center" align="left"> + <p>If a socket connection can not be made to the provider at + the <code>connectionURL</code> an attempt will be made to use the + <code>alternateURL</code>.</p> + </td></tr><tr><td valign="center" align="left"><code>authentication</code></td><td valign="center" align="left"> + <p>A string specifying the type of authentication to use. + "none", "simple", "strong" or a provider specific definition + can be used. If no value is given the providers default is used.</p> + </td></tr><tr><td valign="center" align="left"><code>commonRole</code></td><td valign="center" align="left"> + <p>A role name assigned to each successfully authenticated user in + addition to the roles retrieved from LDAP. If not specified, only + the roles retrieved via LDAP are used.</p> + </td></tr><tr><td valign="center" align="left"><code>connectionName</code></td><td valign="center" align="left"> + <p>The directory username to use when establishing a + connection to the directory for LDAP search operations. If not + specified an anonymous connection is made, which is often + sufficient unless you specify the <code>userPassword</code> + property.</p> + </td></tr><tr><td valign="center" align="left"><code>connectionPassword</code></td><td valign="center" align="left"> + <p>The directory password to use when establishing a + connection to the directory for LDAP search operations. If not + specified an anonymous connection is made, which is often + sufficient unless you specify the <code>userPassword</code> + property.</p> + </td></tr><tr><td valign="center" align="left"><code>connectionTimeout</code></td><td valign="center" align="left"> + <p>The timeout in milliseconds to use when establishing the connection + to the LDAP directory. If not specified, a value of 5000 (5 seconds) is + used.</p> + </td></tr><tr><td valign="center" align="left"><strong><code>connectionURL</code></strong></td><td valign="center" align="left"> + <p>The connection URL to be passed to the JNDI driver when + establishing a connection to the directory.</p> + </td></tr><tr><td valign="center" align="left"><code>contextFactory</code></td><td valign="center" align="left"> + <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> + </td></tr><tr><td valign="center" align="left"><code>derefAliases</code></td><td valign="center" align="left"> + <p>A string specifying how aliases are to be dereferenced during + search operations. The allowed values are "always", "never", + "finding" and "searching". If not specified, "always" is used.</p> + </td></tr><tr><td valign="center" align="left"><code>digest</code></td><td valign="center" align="left"> + <p>The digest algorithm to apply to the plaintext password offered + by the user before comparing it with the value retrieved from the + directory. Valid values are those accepted for the algorithm name + by the <code>java.security.MessageDigest</code> class. If not + specified the plaintext password is assumed to be retrieved. Not + required unless <code>userPassword</code> is specified</p> + </td></tr><tr><td valign="center" align="left"><code>protocol</code></td><td valign="center" align="left"> + <p>A string specifying the security protocol to use. If not given + the providers default is used.</p> + </td></tr><tr><td valign="center" align="left"><code>referrals</code></td><td valign="center" align="left"> + <p>How do we handle JNDI referrals? Allowed values are + "ignore", "follow", or "throw" (see javax.naming.Context.REFERRAL + for more information). + Microsoft Active Directory often returns referrals. + If you need to follow them set referrals to "follow". + Caution: if your DNS is not part of AD, the LDAP client lib might try + to resolve your domain name in DNS to find another LDAP server.</p> + </td></tr><tr><td valign="center" align="left"><code>roleBase</code></td><td valign="center" align="left"> + <p>The base directory entry for performing role searches. If + not specified the top-level element in the directory context + will be used.</p> + </td></tr><tr><td valign="center" align="left"><code>roleName</code></td><td valign="center" align="left"> + <p>The name of the attribute that contains role names in the + directory entries found by a role search. In addition you can + use the <code>userRoleName</code> property to specify the name + of an attribute, in the user's entry, containing additional + role names. If <code>roleName</code> is not specified a role + search does not take place, and roles are taken only from the + user's entry.</p> + </td></tr><tr><td valign="center" align="left"><code>roleSearch</code></td><td valign="center" align="left"> + <p>The LDAP filter expression used for performing role + searches. Use <code>{0}</code> to substitute the + distinguished name (DN) of the user, and/or <code>{1}</code> to + substitute the username. If not specified a role search does + not take place and roles are taken only from the attribute in + the user's entry specified by the <code>userRoleName</code> + property.</p> + </td></tr><tr><td valign="center" align="left"><code>roleSubtree</code></td><td valign="center" align="left"> + <p>Set to <code>true</code> if you want to search the entire + subtree of the element specified by the <code>roleBase</code> + property for role entries associated with the user. The + default value of <code>false</code> causes only the top level + to be searched.</p> + </td></tr><tr><td valign="center" align="left"><code>userBase</code></td><td valign="center" align="left"> + <p>The base element for user searches performed using the + <code>userSearch</code> expression. Not used if you are using + the <code>userPattern</code> expression.</p> + </td></tr><tr><td valign="center" align="left"><code>userPassword</code></td><td valign="center" align="left"> + <p>Name of the attribute in the user's entry containing the + user's password. If you specify this value, JNDIRealm will + bind to the directory using the values specified by + <code>connectionName</code> and + <code>connectionPassword</code> properties, and retrieve the + corresponding attribute for comparison to the value specified + by the user being authenticated. If you do + <strong>not</strong> specify this value, JNDIRealm will + attempt a simple bind to the directory using the DN of the + user's entry and the password presented by the user, with a + successful bind being interpreted as an authenticated + user.</p> + </td></tr><tr><td valign="center" align="left"><code>userPattern</code></td><td valign="center" align="left"> + <p>Pattern for the distinguished name (DN) of the user's + directory entry, with <code>{0}</code> marking where the + actual username should be inserted. You can use this property + instead of <code>userSearch</code>, <code>userSubtree</code> + and <code>userBase</code> when the distinguished name contains + the username and is otherwise the same for all users.</p> + </td></tr><tr><td valign="center" align="left"><code>userRoleName</code></td><td valign="center" align="left"> + <p>The name of an attribute in the user's directory entry + containing zero or more values for the names of roles assigned + to this user. In addition you can use the + <code>roleName</code> property to specify the name of an + attribute to be retrieved from individual role entries found + by searching the directory. If <code>userRoleName</code> is + not specified all the roles for a user derive from the role + search.</p> + </td></tr><tr><td valign="center" align="left"><code>userSearch</code></td><td valign="center" align="left"> + <p>The LDAP filter expression to use when searching for a + user's directory entry, with <code>{0}</code> marking where + the actual username should be inserted. Use this property + (along with the <code>userBase</code> and + <code>userSubtree</code> properties) instead of + <code>userPattern</code> to search the directory for the + user's entry.</p> + </td></tr><tr><td valign="center" align="left"><code>userSubtree</code></td><td valign="center" align="left"> + <p>Set to <code>true</code> if you want to search the entire + subtree of the element specified by the <code>userBase</code> + property for the user's entry. The default value of + <code>false</code> causes only the top level to be searched. + Not used if you are using the <code>userPattern</code> + expression.</p> + </td></tr></table> + + <p>See the <a href="../realm-howto.html">Container-Managed Security Guide</a> for more + information on setting up container managed security using the + JNDI Directory Realm component.</p> + + + <h3>UserDatabase Realm (org.apache.catalina.realm.UserDatabaseRealm)</h3> + + <p>The <strong>UserDatabase Realm</strong> is a Realm implementation + that is based on a UserDatabase resource made available through the global + JNDI resources configured for this Tomcat instance.</p> + + <p>The Memory Based Realm implementation supports the following + additional attributes:</p> + + <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><strong><code>resourceName</code></strong></td><td valign="center" align="left"> + <p>The name of the resource that this realm will use for user, password + and role information.</p> + </td></tr></table> + + <p>See the + <a href="../realm-howto.html">Container-Managed Security Guide</a> for more + information on setting up container managed security using the UserDatabase + Realm component and the + <a href="../jndi-resources-howto.html">JNDI resources how-to</a> for more + information on how to configure a UserDatabase resource.</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> + + <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><code>digest</code></td><td valign="center" align="left"> + <p>The digest algorithm used to store passwords in non-plaintext + formats. Valid values are those accepted for the algorithm name by the + <code>java.security.MessageDigest</code> class. If not specified, + passwords are stored in clear text.</p> + </td></tr><tr><td valign="center" align="left"><code>pathname</code></td><td valign="center" align="left"> + <p>Absolute or relative (to $CATALINA_BASE) 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> + </td></tr></table> + + <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><tomcat-users></code>. + </li> + <li>Each authorized user must be represented by a single XML element + <code><user></code>, nested inside the root element.</li> + <li>Each <code><user></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 the <a href="../realm-howto.html">Container-Managed Security Guide</a> for more + information on setting up container managed security using the + Memory Based Realm component.</p> + + <h3>JAAS Realm (org.apache.catalina.realm.JAASRealm)</h3> + + <p><strong>JAASRealm</strong> is an implementation of the Tomcat 6 + <code>Realm</code> interface that authenticates users through the Java + Authentication & Authorization Service (JAAS) framework which is now + provided as part of the standard J2SE API.</p> + + <p>Using JAASRealm gives the developer the ability to combine practically + any conceivable security realm with Tomcat's CMA.</p> + + <p>JAASRealm is prototype for Tomcat of the JAAS-based J2EE authentication + framework for J2EE v1.4, based on the <a href="http://www.jcp.org/en/jsr/detail?id=196";>JCP Specification Request + 196</a> to enhance container-managed security and promote 'pluggable' + authentication mechanisms whose implementations would be + container-independent.</p> + + <p>Based on the JAAS login module and principal + (see <code>javax.security.auth.spi.LoginModule</code> and + <code>javax.security.Principal</code>), you can develop your own security + mechanism or wrap another third-party mechanism for integration with the CMA + as implemented by Tomcat.</p> + + <p>The JAAS Realm implementation supports the following additional + attributes:</p> + + <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><strong><code>appName</code></strong></td><td valign="center" align="left"> + <p>The name of the application as configured in your login configuration + file + (<a href="http://java.sun.com/j2se/1.4.1/docs/guide/security/jaas/tutorials/LoginConfigFile.html";>JAAS LoginConfig</a>).</p> + </td></tr><tr><td valign="center" align="left"><strong><code>userClassNames</code></strong></td><td valign="center" align="left"> + <p>A comma-separated list of the names of the classes that you have made + for your user <code>Principals</code>.</p> + </td></tr><tr><td valign="center" align="left"><code>roleClassNames</code></td><td valign="center" align="left"> + <p>A comma-separated list of the names of the classes that you have made + for your role <code>Principals</code>.</p> + </td></tr><tr><td valign="center" align="left"><code>useContextClassLoader</code></td><td valign="center" align="left"> + <p>Instructs JAASRealm to use the context class loader for loading the + user-specified <code>LoginModule</code> class and associated + <code>Principal</code> classes. The default value is <code>true</code>, + which is backwards-compatible with the way Tomcat 5 works. To load + classes using the container's classloader, specify + <code>false</code>.</p> + </td></tr></table> + + <p>See the <a href="../realm-howto.html">Container-Managed Security + Guide</a> for more information on setting up container managed security + using the JAAS Realm component.</p> + + <h3>Combined Realm (org.apache.catalina.realm.CombinedRealm)</h3> + + <p><strong>CombinedRealm</strong> is an implementation of the Tomcat 6 + <code>Realm</code> interface that authenticates users through one or more + sub-Realms.</p> + + <p>Using CombinedRealm gives the developer the ability to combine multiple + Realms of the same or different types. This can be used to authenticate + against different sources, provide fall back in case one Realm fails or for + any other purpose that requires multiple Realms.</p> + + <p>Sub-realms are defined by nesting <code>Realm</code> elements inside the + <code>Realm</code> element that defines the CombinedRealm. Authentication + will be attempted against each <code>Realm</code> in the order they are + listed. Authentication against any Realm will be sufficient to authenticate + the user.</p> + + <p>The CombinedRealm implementation does not support any additional + attributes.</p> + + <p>See the <a href="../realm-howto.html">Container-Managed Security + Guide</a> for more information on setting up container managed security + using the CombinedRealm component.</p> + + <h3>LockOut Realm (org.apache.catalina.realm.LockOutRealm)</h3> + + <p><strong>LockOutRealm</strong> is an implementation of the Tomcat 6 + <code>Realm</code> interface that extends the CombinedRealm to provide lock + out functionality to provide a user lock out mechanism if there are too many + failed authentication attempts in a given period of time.</p> + + <p>To ensure correct operation, there is a reasonable degree of + synchronization in this Realm.</p> + + <p>This Realm does not require modification to the underlying Realms or the + associated user storage mechanisms. It achieves this by recording all failed + logins, including those for users that do not exist. To prevent a DOS by + deliberating making requests with invalid users (and hence causing this + cache to grow) the size of the list of users that have failed authentication + is limited.</p> + + <p>Sub-realms are defined by nesting <code>Realm</code> elements inside the + <code>Realm</code> element that defines the LockOutRealm. Authentication + will be attempted against each <code>Realm</code> in the order they are + listed. Authentication against any Realm will be sufficient to authenticate + the user.</p> + + <p>The LockOutRealm implementation supports the following additional + attributes.</p> + + <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><code>cacheRemovalWarningTime</code></td><td valign="center" align="left"> + <p>If a failed user is removed from the cache because the cache is too + big before it has been in the cache for at least this period of time (in + seconds) a warning message will be logged. Defaults to 3600 (1 hour).</p> + </td></tr><tr><td valign="center" align="left"><code>cacheSize</code></td><td valign="center" align="left"> + <p>Number of users that have failed authentication to keep in cache. Over + time the cache will grow to this size and may not shrink. Defaults to + 1000.</p> + </td></tr><tr><td valign="center" align="left"><code>failureCount</code></td><td valign="center" align="left"> + <p>The number of times in a row a user has to fail authentication to be + locked out. Defaults to 5.</p> + </td></tr><tr><td valign="center" align="left"><code>lockOutTime</code></td><td valign="center" align="left"> + <p>The time (in seconds) a user is locked out for after too many + authentication failures. Defaults to 300 (5 minutes).</p> + </td></tr></table> + + <p>See the <a href="../realm-howto.html">Container-Managed Security + Guide</a> for more information on setting up container managed security + using the LockOutRealm component.</p> + + </blockquote></td></tr></table> + + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Nested Components"><!--()--></a><a name="Nested_Components"><strong>Nested Components</strong></a></font></td></tr><tr><td><blockquote> + + <h3>CombinedRealm Implementation</h3> + + <p>If you are using the <em>CombinedRealm Implementation</em> or a Realm + that extends the CombinedRealm, e.g. the LockOutRealm, + <strong><Realm></strong> elements may be nested inside it.</p> + + <h3>Other Realm Implementations</h3> + + <p>No other Realm implementation supports nested components.</p> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Special Features"><!--()--></a><a name="Special_Features"><strong>Special Features</strong></a></font></td></tr><tr><td><blockquote> + + <p>See <a href="host.html">Single Sign On</a> for information about + configuring Single Sign On support for a virtual host.</p> + +</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em> + Copyright © 1999-2010, Apache Software Foundation + </em></font></div></td></tr></table></body></html> \ No newline at end of file
