You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by rj...@apache.org on 2012/12/05 21:21:01 UTC
svn commit: r1417624 [17/38] - in /tomcat/site/trunk/docs/tomcat-8.0-doc: ./
api/ appdev/ appdev/sample/ appdev/sample/docs/ appdev/sample/src/
appdev/sample/src/mypackage/ appdev/sample/web/ appdev/sample/web/WEB-INF/
appdev/sample/web/images/ archite...
Added: tomcat/site/trunk/docs/tomcat-8.0-doc/config/realm.html
URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-8.0-doc/config/realm.html?rev=1417624&view=auto
==============================================================================
--- tomcat/site/trunk/docs/tomcat-8.0-doc/config/realm.html (added)
+++ tomcat/site/trunk/docs/tomcat-8.0-doc/config/realm.html Wed Dec 5 20:20:35 2012
@@ -0,0 +1,836 @@
+<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 8 Configuration Reference (8.0.0-dev) - The Realm Component</title><meta name="author" content="Craig R. McClanahan"><style type="text/css" media="print">
+ .noPrint {display: none;}
+ td#mainBody {width: 100%;}
+ </style><style type="text/css">
+ code {background-color:rgb(224,255,255);padding:0 0.1em;}
+ code.attributeName, code.propertyName {background-color:transparent;}
+ </style><style type="text/css">
+ .wrapped-source code { display: block; background-color: transparent; }
+ .wrapped-source div { margin: 0 0 0 1.25em; }
+ .wrapped-source p { margin: 0 0 0 1.25em; text-indent: -1.25em; }
+ </style><style type="text/css">
+ p.notice {
+ border: 1px solid rgb(255, 0, 0);
+ background-color: rgb(238, 238, 238);
+ color: rgb(0, 51, 102);
+ padding: 0.5em;
+ margin: 1em 2em 1em 1em;
+ }
+ </style></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="../images/tomcat.gif" align="right" alt="
+ The Apache Tomcat Servlet/JSP Container
+ " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 8</font></h1><font face="arial,helvetica,sanserif">Version 8.0.0-dev, Dec 5 2012</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="../images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap class="noPrint"><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><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</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">Executo
r</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="globalresources.html">Global Resources</a></li><li><a href="jar-scanner.html">JarScanner</a></li><li><a href="listeners.html">Listeners</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/M
embership</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="cluster-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>Other</strong></p><ul><li><a href="filter.html">Filter</a></li><li><a href="systemprops.html">System properties</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>The Realm Component</h1><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><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="#JDBC_Database_Realm_-_org.apache.catalina.realm.JDBCRealm">JDBC Database Realm - org.apache.catalina.realm.JDBCRealm</a></li><li><a href="#DataSource_Database_Realm_-_org.apache.catalina.realm.DataSourceRealm">DataSource Database Realm - org.apache.catalina.realm.DataSourceRealm</a></li><li><a href="#JNDI_Directory_Realm_-_org.apache.catalina.realm.JNDIRealm">JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm</a></li><li><a href="#UserDatabase_Realm_-_org.apache.catalina.realm.UserDatabaseRealm">UserDatabase Realm - org.apache.catalina.realm.UserDatabaseRealm</a></li><li><a href="#Memory_Based_Realm_-_org.apache.catalina.realm.MemoryRealm">Memory Based Realm - org.apache.catalina.realm.MemoryRealm</a></li><li><a href="#JAAS_Realm_-_org.apache.catalina.realm.JAASRealm">JAAS Realm - org.apache.catalina
.realm.JAASRealm</a></li><li><a href="#Combined_Realm_-_org.apache.catalina.realm.CombinedRealm">Combined Realm - org.apache.catalina.realm.CombinedRealm</a></li><li><a href="#LockOut_Realm_-_org.apache.catalina.realm.LockOutRealm">LockOut Realm - org.apache.catalina.realm.LockOutRealm</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 border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><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 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.</p>
+ </em></blockquote>
+
+</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
+
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><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 border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><strong><code class="attributeName">className</code></strong></td><td align="left" valign="center">
+ <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>
+
+ <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>
+
+ </blockquote></td></tr></table>
+
+
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="JDBC Database Realm - org.apache.catalina.realm.JDBCRealm"><!--()--></a><a name="JDBC_Database_Realm_-_org.apache.catalina.realm.JDBCRealm"><strong>JDBC Database Realm - org.apache.catalina.realm.JDBCRealm</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p>The <strong>JDBC Database Realm</strong> connects Tomcat 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 border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">allRolesMode</code></td><td align="left" valign="center">
+ <p>This attribute controls how the special role name <code>*</code> is
+ handled when processing authorization constraints in web.xml. By
+ default, the specification compliant value of <code>strict</code> is
+ used which means that the user must be assigned one of the roles defined
+ in web.xml. The alternative values are <code>authOnly</code> which means
+ that the user must be authenticated but no check is made for assigned
+ roles and <code>strictAuthOnly</code> which means that the user must be
+ authenticated and no check will be made for assigned roles unless roles
+ are defined in web.xml in which case the user must be assigned at least
+ one of those roles.</p>
+ <p>When this attribute has the value of <code>authOnly</code> or
+ <code>strictAuthOnly</code>, the <strong>roleNameCol</strong> and
+ <strong>userRoleTable</strong> attributes become optional. If those two
+ attributes are omitted, the user's roles will not be loaded by this
+ Realm.</p>
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">connectionName</code></strong></td><td align="left" valign="center">
+ <p>The database username to use when establishing the JDBC
+ connection.</p>
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">connectionPassword</code></strong></td><td align="left" valign="center">
+ <p>The database password to use when establishing the JDBC
+ connection.</p>
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">connectionURL</code></strong></td><td align="left" valign="center">
+ <p>The connection URL to be passed to the JDBC driver when
+ establishing a database connection.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">digest</code></td><td align="left" valign="center">
+ <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 align="left" valign="center"><code class="attributeName">digestEncoding</code></td><td align="left" valign="center">
+ <p>The charset for encoding digests. If not specified, the platform
+ default will be used.</p>
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">driverName</code></strong></td><td align="left" valign="center">
+ <p>Fully qualified Java class name of the JDBC driver to be
+ used to connect to the authentication database.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">roleNameCol</code></td><td align="left" valign="center">
+ <p>Name of the column, in the "user roles" table, which contains
+ a role name assigned to the corresponding user.</p>
+ <p>This attribute is <strong>required</strong> in majority of
+ configurations. See <strong>allRolesMode</strong> attribute for
+ a rare case when it can be omitted.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">stripRealmForGss</code></td><td align="left" valign="center">
+ <p>When processing users authenticated via the GSS-API, this attribute
+ controls if any "@..." is removed from the end of the user
+ name. If not specified, the default is <code>true</code>.</p>
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">userCredCol</code></strong></td><td align="left" valign="center">
+ <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 align="left" valign="center"><strong><code class="attributeName">userNameCol</code></strong></td><td align="left" valign="center">
+ <p>Name of the column, in the "users" and "user roles" table,
+ that contains the user's username.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">userRoleTable</code></td><td align="left" valign="center">
+ <p>Name of the "user roles" table, which must contain columns
+ named by the <code>userNameCol</code> and <code>roleNameCol</code>
+ attributes.</p>
+ <p>This attribute is <strong>required</strong> in majority of
+ configurations. See <strong>allRolesMode</strong> attribute for
+ a rare case when it can be omitted.</p>
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">userTable</code></strong></td><td align="left" valign="center">
+ <p>Name of the "users" table, which must contain columns named
+ by the <code>userNameCol</code> and <code>userCredCol</code>
+ attributes.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">X509UsernameRetrieverClassName</code></td><td align="left" valign="center">
+ <p>When using X509 client certificates, this specifies the class name
+ that will be used to retrieve the user name from the certificate.
+ The class must implement the
+ <code>org.apache.catalina.realm.X509UsernameRetriever</code>
+ interface. The default is to use the certificate's SubjectDN
+ as the username.</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>
+
+ </blockquote></td></tr></table>
+
+
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="DataSource Database Realm - org.apache.catalina.realm.DataSourceRealm"><!--()--></a><a name="DataSource_Database_Realm_-_org.apache.catalina.realm.DataSourceRealm"><strong>DataSource Database Realm - org.apache.catalina.realm.DataSourceRealm</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p>The <strong>DataSource Database Realm</strong> connects Tomcat 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 border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">allRolesMode</code></td><td align="left" valign="center">
+ <p>This attribute controls how the special role name <code>*</code> is
+ handled when processing authorization constraints in web.xml. By
+ default, the specification compliant value of <code>strict</code> is
+ used which means that the user must be assigned one of the roles defined
+ in web.xml. The alternative values are <code>authOnly</code> which means
+ that the user must be authenticated but no check is made for assigned
+ roles and <code>strictAuthOnly</code> which means that the user must be
+ authenticated and no check will be made for assigned roles unless roles
+ are defined in web.xml in which case the user must be assigned at least
+ one of those roles.</p>
+ <p>When this attribute has the value of <code>authOnly</code> or
+ <code>strictAuthOnly</code>, the <strong>roleNameCol</strong> and
+ <strong>userRoleTable</strong> attributes become optional. If those two
+ attributes are omitted, the user's roles will not be loaded by this
+ Realm.</p>
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">dataSourceName</code></strong></td><td align="left" valign="center">
+ <p>The name of the JNDI JDBC DataSource for this Realm.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">digest</code></td><td align="left" valign="center">
+ <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 align="left" valign="center"><code class="attributeName">localDataSource</code></td><td align="left" valign="center">
+ <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 align="left" valign="center"><code class="attributeName">roleNameCol</code></td><td align="left" valign="center">
+ <p>Name of the column, in the "user roles" table, which contains
+ a role name assigned to the corresponding user.</p>
+ <p>This attribute is <strong>required</strong> in majority of
+ configurations. See <strong>allRolesMode</strong> attribute for
+ a rare case when it can be omitted.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">stripRealmForGss</code></td><td align="left" valign="center">
+ <p>When processing users authenticated via the GSS-API, this attribute
+ controls if any "@..." is removed from the end of the user
+ name. If not specified, the default is <code>true</code>.</p>
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">userCredCol</code></strong></td><td align="left" valign="center">
+ <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 align="left" valign="center"><strong><code class="attributeName">userNameCol</code></strong></td><td align="left" valign="center">
+ <p>Name of the column, in the "users" and "user roles" table,
+ that contains the user's username.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">userRoleTable</code></td><td align="left" valign="center">
+ <p>Name of the "user roles" table, which must contain columns
+ named by the <code>userNameCol</code> and <code>roleNameCol</code>
+ attributes.</p>
+ <p>This attribute is <strong>required</strong> in majority of
+ configurations. See <strong>allRolesMode</strong> attribute for
+ a rare case when it can be omitted.</p>
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">userTable</code></strong></td><td align="left" valign="center">
+ <p>Name of the "users" table, which must contain columns named
+ by the <code>userNameCol</code> and <code>userCredCol</code>
+ attributes.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">X509UsernameRetrieverClassName</code></td><td align="left" valign="center">
+ <p>When using X509 client certificates, this specifies the class name
+ that will be used to retrieve the user name from the certificate.
+ The class must implement the
+ <code>org.apache.catalina.realm.X509UsernameRetriever</code>
+ interface. The default is to use the certificate's SubjectDN
+ as the username.</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>
+
+ </blockquote></td></tr></table>
+
+
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm"><!--()--></a><a name="JNDI_Directory_Realm_-_org.apache.catalina.realm.JNDIRealm"><strong>JNDI Directory Realm - org.apache.catalina.realm.JNDIRealm</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p>The <strong>JNDI Directory Realm</strong> connects Tomcat 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 border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">adCompat</code></td><td align="left" valign="center">
+ <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 align="left" valign="center"><code class="attributeName">allRolesMode</code></td><td align="left" valign="center">
+ <p>This attribute controls how the special role name <code>*</code> is
+ handled when processing authorization constraints in web.xml. By
+ default, the specification compliant value of <code>strict</code> is
+ used which means that the user must be assigned one of the roles defined
+ in web.xml. The alternative values are <code>authOnly</code> which means
+ that the user must be authenticated but no check is made for assigned
+ roles and <code>strictAuthOnly</code> which means that the user must be
+ authenticated and no check will be made for assigned roles unless roles
+ are defined in web.xml in which case the user must be assigned at least
+ one of those roles.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">alternateURL</code></td><td align="left" valign="center">
+ <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 align="left" valign="center"><code class="attributeName">authentication</code></td><td align="left" valign="center">
+ <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 align="left" valign="center"><code class="attributeName">commonRole</code></td><td align="left" valign="center">
+ <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 align="left" valign="center"><code class="attributeName">connectionName</code></td><td align="left" valign="center">
+ <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 align="left" valign="center"><code class="attributeName">connectionPassword</code></td><td align="left" valign="center">
+ <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 align="left" valign="center"><code class="attributeName">connectionTimeout</code></td><td align="left" valign="center">
+ <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 align="left" valign="center"><strong><code class="attributeName">connectionURL</code></strong></td><td align="left" valign="center">
+ <p>The connection URL to be passed to the JNDI driver when
+ establishing a connection to the directory.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">contextFactory</code></td><td align="left" valign="center">
+ <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 align="left" valign="center"><code class="attributeName">derefAliases</code></td><td align="left" valign="center">
+ <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 align="left" valign="center"><code class="attributeName">digest</code></td><td align="left" valign="center">
+ <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 align="left" valign="center"><code class="attributeName">protocol</code></td><td align="left" valign="center">
+ <p>A string specifying the security protocol to use. If not given
+ the providers default is used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">referrals</code></td><td align="left" valign="center">
+ <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 align="left" valign="center"><code class="attributeName">roleBase</code></td><td align="left" valign="center">
+ <p>The base directory entry for performing role searches. If not
+ specified the top-level element in the directory context will be used.
+ If specified it may optionally include pattern replacements
+ "{0}".."{n}" corresponding to the name parts of the
+ user's distinguished name (as returned by
+ <code>javax.naming.Name.get()</code>).</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">roleName</code></td><td align="left" valign="center">
+ <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.</p>
+ <p>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 align="left" valign="center"><code class="attributeName">roleNested</code></td><td align="left" valign="center">
+ <p>Set to <code>true</code> if you want to nest roles into roles.
+ When a role search is performed and the value of this property is
+ <code>true</code>, the search will be repeated recursively to find
+ all the roles that belong to the user either directly or indirectly.
+ If not specified, the default value of <code>false</code> is used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">roleSearch</code></td><td align="left" valign="center">
+ <p>The LDAP filter expression used for performing role
+ searches.</p>
+
+ <p>Use <code>{0}</code> to substitute the distinguished name (DN)
+ of the user, and/or <code>{1}</code> to substitute the username,
+ and/or <code>{2}</code> for the value of an attribute from the
+ user's directory entry, of the authenticated user.
+ The name of the attribute that provides the value for <code>{2}</code>
+ is configured by the <code>userRoleAttribute</code> property.</p>
+
+ <p>When <code>roleNested</code> property is <code>true</code>,
+ this filter expression will be also used to recursively search for
+ other roles, which indirectly belong to this user. To find the
+ roles that match the newly found role, the following values
+ are used:
+ <code>{0}</code> is substituted by the distinguished name of the newly
+ found role, and both <code>{1}</code> and <code>{2}</code> are
+ substituted by the name of the role (see the <code>roleName</code>
+ property). The <code>userRoleAttribute</code> property is not
+ applicable to this search.</p>
+
+ <p>If this property is 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 align="left" valign="center"><code class="attributeName">roleSearchAsUser</code></td><td align="left" valign="center">
+ <p> When searching for user roles, should the search be performed as the
+ user currently being authenticated? If false,
+ <code>connectionName</code> and <code>connectionPassword</code> will be
+ used if specified, else an anonymous. If not specified, the default
+ value of <code>false</code> is used. Note that when accessing the
+ directory using delegated credentials, this attribute is always ignored
+ and the search is performed using the delegated credentials.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">roleSubtree</code></td><td align="left" valign="center">
+ <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 align="left" valign="center"><code class="attributeName">sizeLimit</code></td><td align="left" valign="center">
+ <p>Specifies the maximum number of records to return when using the
+ <code>userSearch</code> attribute. If not specified, the default of
+ <code>0</code> is used which indicates no limit.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">stripRealmForGss</code></td><td align="left" valign="center">
+ <p>When processing users authenticated via the GSS-API, this attribute
+ controls if any "@..." is removed from the end of the user
+ name. If not specified, the default is <code>true</code>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">timeLimit</code></td><td align="left" valign="center">
+ <p>Specifies the time (in milliseconds) to wait for records to be
+ returned when using the <code>userSearch</code> attribute. If not
+ specified, the default of <code>0</code> is used which indicates no
+ limit.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">useDelegatedCredential</code></td><td align="left" valign="center">
+ <p>When the JNIRealm is used with the SPNEGO authenticator, delegated
+ credentials for the user may be available. If such credentials are
+ present, this attribute controls whether are not they are used to
+ connect to the directory. If not specified, the default value of
+ <code>true</code> is used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">userBase</code></td><td align="left" valign="center">
+ <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 align="left" valign="center"><code class="attributeName">userPassword</code></td><td align="left" valign="center">
+ <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 align="left" valign="center"><code class="attributeName">userPattern</code></td><td align="left" valign="center">
+ <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. Note that
+ when accessing the directory using delegated credentials, this
+ attribute is always ignored and <code>userSearch</code>,
+ <code>userSubtree</code> and <code>userBase</code> are always
+ used instead.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">userRoleName</code></td><td align="left" valign="center">
+ <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 align="left" valign="center"><code class="attributeName">userRoleAttribute</code></td><td align="left" valign="center">
+ <p>The name of an attribute in the user's directory entry
+ containing the value that you wish to use when you search for
+ roles. This is especially useful for RFC 2307 where
+ the role memberUid can be the <code>uid</code> or the
+ <code>uidNumber</code> of the user. This value will be
+ marked as <code>{2}</code> in your role search filter expression.
+ This value will NOT be available for nested role searches.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">userSearch</code></td><td align="left" valign="center">
+ <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 align="left" valign="center"><code class="attributeName">userSubtree</code></td><td align="left" valign="center">
+ <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><tr><td align="left" valign="center"><code class="attributeName">X509UsernameRetrieverClassName</code></td><td align="left" valign="center">
+ <p>When using X509 client certificates, this specifies the class name
+ that will be used to retrieve the user name from the certificate.
+ The class must implement the
+ <code>org.apache.catalina.realm.X509UsernameRetriever</code>
+ interface. The default is to use the certificate's SubjectDN
+ as the username.</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>
+
+ </blockquote></td></tr></table>
+
+
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="UserDatabase Realm - org.apache.catalina.realm.UserDatabaseRealm"><!--()--></a><a name="UserDatabase_Realm_-_org.apache.catalina.realm.UserDatabaseRealm"><strong>UserDatabase Realm - org.apache.catalina.realm.UserDatabaseRealm</strong></a></font></td></tr><tr><td><blockquote>
+
+ <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 UserDatabase Realm implementation supports the following
+ additional attributes:</p>
+
+ <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">allRolesMode</code></td><td align="left" valign="center">
+ <p>This attribute controls how the special role name <code>*</code> is
+ handled when processing authorization constraints in web.xml. By
+ default, the specification compliant value of <code>strict</code> is
+ used which means that the user must be assigned one of the roles defined
+ in web.xml. The alternative values are <code>authOnly</code> which means
+ that the user must be authenticated but no check is made for assigned
+ roles and <code>strictAuthOnly</code> which means that the user must be
+ authenticated and no check will be made for assigned roles unless roles
+ are defined in web.xml in which case the user must be assigned at least
+ one of those roles.</p>
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">resourceName</code></strong></td><td align="left" valign="center">
+ <p>The name of the global <code>UserDatabase</code> resource
+ that this realm will use for user, password and role information.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">X509UsernameRetrieverClassName</code></td><td align="left" valign="center">
+ <p>When using X509 client certificates, this specifies the class name
+ that will be used to retrieve the user name from the certificate.
+ The class must implement the
+ <code>org.apache.catalina.realm.X509UsernameRetriever</code>
+ interface. The default is to use the certificate's SubjectDN
+ as the username.</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>
+
+ </blockquote></td></tr></table>
+
+
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Memory Based Realm - org.apache.catalina.realm.MemoryRealm"><!--()--></a><a name="Memory_Based_Realm_-_org.apache.catalina.realm.MemoryRealm"><strong>Memory Based Realm - org.apache.catalina.realm.MemoryRealm</strong></a></font></td></tr><tr><td><blockquote>
+
+ <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 border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">allRolesMode</code></td><td align="left" valign="center">
+ <p>This attribute controls how the special role name <code>*</code> is
+ handled when processing authorization constraints in web.xml. By
+ default, the specification compliant value of <code>strict</code> is
+ used which means that the user must be assigned one of the roles defined
+ in web.xml. The alternative values are <code>authOnly</code> which means
+ that the user must be authenticated but no check is made for assigned
+ roles and <code>strictAuthOnly</code> which means that the user must be
+ authenticated and no check will be made for assigned roles unless roles
+ are defined in web.xml in which case the user must be assigned at least
+ one of those roles.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">digest</code></td><td align="left" valign="center">
+ <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 align="left" valign="center"><code class="attributeName">pathname</code></td><td align="left" valign="center">
+ <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><tr><td align="left" valign="center"><code class="attributeName">stripRealmForGss</code></td><td align="left" valign="center">
+ <p>When processing users authenticated via the GSS-API, this attribute
+ controls if any "@..." is removed from the end of the user
+ name. If not specified, the default is <code>true</code>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">X509UsernameRetrieverClassName</code></td><td align="left" valign="center">
+ <p>When using X509 client certificates, this specifies the class name
+ that will be used to retrieve the user name from the certificate.
+ The class must implement the
+ <code>org.apache.catalina.realm.X509UsernameRetriever</code>
+ interface. The default is to use the certificate's SubjectDN
+ as the username.</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>
+
+ </blockquote></td></tr></table>
+
+
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="JAAS Realm - org.apache.catalina.realm.JAASRealm"><!--()--></a><a name="JAAS_Realm_-_org.apache.catalina.realm.JAASRealm"><strong>JAAS Realm - org.apache.catalina.realm.JAASRealm</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p><strong>JAASRealm</strong> is an implementation of the Tomcat
+ <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 border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">allRolesMode</code></td><td align="left" valign="center">
+ <p>This attribute controls how the special role name <code>*</code> is
+ handled when processing authorization constraints in web.xml. By
+ default, the specification compliant value of <code>strict</code> is
+ used which means that the user must be assigned one of the roles defined
+ in web.xml. The alternative values are <code>authOnly</code> which means
+ that the user must be authenticated but no check is made for assigned
+ roles and <code>strictAuthOnly</code> which means that the user must be
+ authenticated and no check will be made for assigned roles unless roles
+ are defined in web.xml in which case the user must be assigned at least
+ one of those roles.</p>
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">appName</code></strong></td><td align="left" valign="center">
+ <p>The name of the application as configured in your login configuration
+ file
+ (<a href="http://docs.oracle.com/javase/1.4.2/docs/guide/security/jaas/tutorials/LoginConfigFile.html">JAAS LoginConfig</a>).</p>
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">userClassNames</code></strong></td><td align="left" valign="center">
+ <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 align="left" valign="center"><code class="attributeName">roleClassNames</code></td><td align="left" valign="center">
+ <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 align="left" valign="center"><code class="attributeName">stripRealmForGss</code></td><td align="left" valign="center">
+ <p>When processing users authenticated via the GSS-API, this attribute
+ controls if any "@..." is removed from the end of the user
+ name. If not specified, the default is <code>true</code>.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">useContextClassLoader</code></td><td align="left" valign="center">
+ <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><tr><td align="left" valign="center"><code class="attributeName">X509UsernameRetrieverClassName</code></td><td align="left" valign="center">
+ <p>When using X509 client certificates, this specifies the class name
+ that will be used to retrieve the user name from the certificate.
+ The class must implement the
+ <code>org.apache.catalina.realm.X509UsernameRetriever</code>
+ interface. The default is to use the certificate's SubjectDN
+ as the username.</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>
+
+ </blockquote></td></tr></table>
+
+
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Combined Realm - org.apache.catalina.realm.CombinedRealm"><!--()--></a><a name="Combined_Realm_-_org.apache.catalina.realm.CombinedRealm"><strong>Combined Realm - org.apache.catalina.realm.CombinedRealm</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p><strong>CombinedRealm</strong> is an implementation of the Tomcat
+ <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>
+
+ </blockquote></td></tr></table>
+
+
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="LockOut Realm - org.apache.catalina.realm.LockOutRealm"><!--()--></a><a name="LockOut_Realm_-_org.apache.catalina.realm.LockOutRealm"><strong>LockOut Realm - org.apache.catalina.realm.LockOutRealm</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p><strong>LockOutRealm</strong> is an implementation of the Tomcat
+ <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 border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">cacheRemovalWarningTime</code></td><td align="left" valign="center">
+ <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 align="left" valign="center"><code class="attributeName">cacheSize</code></td><td align="left" valign="center">
+ <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 align="left" valign="center"><code class="attributeName">failureCount</code></td><td align="left" valign="center">
+ <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 align="left" valign="center"><code class="attributeName">lockOutTime</code></td><td align="left" valign="center">
+ <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 border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><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 border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><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><tr class="noPrint"><td width="20%" valign="top" nowrap class="noPrint"></td><td width="80%" valign="top" align="left"><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="comments_section" id="comments_section"><strong>Comments</strong></a></font></td></tr><tr><td><blockquote><p class="notice"><strong>Notice: </strong>This is not a Q&A section.
+ The Apache Comments System is explained
+ <a href="/tomcat-8.0-doc/comments.html">here</a>.
+ Comments should be pointed towards suggestions on improving the documentation
+ or server, and may be removed again by our moderators if they are either
+ implemented or considered invalid/off-topic.
+ Questions on how to manage Apache Tomcat should be directed
+ to our <a href="http://tomcat.apache.org/lists.html">mailing lists</a>.</p><script type="text/javascript"><!--//--><![CDATA[//><!--
+ var comments_shortname = 'tomcat';
+ var comments_identifier = 'http://tomcat.apache.org/tomcat-8.0-doc/config/realm.html';
+ (function(w, d) {
+ if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
+ d.write('<div id="comments_thread"><\/div>');
+ var s = d.createElement('script');
+ s.type = 'text/javascript';
+ s.async = true;
+ s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
+ (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
+ }
+ else {
+ d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.</strong><\/div>');
+ }
+ })(window, document);
+ //--><!]]></script></blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
+ Copyright © 1999-2012, Apache Software Foundation
+ </em></font></div></td></tr></table></body></html>
\ No newline at end of file
Propchange: tomcat/site/trunk/docs/tomcat-8.0-doc/config/realm.html
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: tomcat/site/trunk/docs/tomcat-8.0-doc/config/realm.html
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Added: tomcat/site/trunk/docs/tomcat-8.0-doc/config/resources.html
URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-8.0-doc/config/resources.html?rev=1417624&view=auto
==============================================================================
--- tomcat/site/trunk/docs/tomcat-8.0-doc/config/resources.html (added)
+++ tomcat/site/trunk/docs/tomcat-8.0-doc/config/resources.html Wed Dec 5 20:20:35 2012
@@ -0,0 +1,164 @@
+<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 8 Configuration Reference (8.0.0-dev) - The Resources Component</title><style type="text/css" media="print">
+ .noPrint {display: none;}
+ td#mainBody {width: 100%;}
+ </style><style type="text/css">
+ code {background-color:rgb(224,255,255);padding:0 0.1em;}
+ code.attributeName, code.propertyName {background-color:transparent;}
+ </style><style type="text/css">
+ .wrapped-source code { display: block; background-color: transparent; }
+ .wrapped-source div { margin: 0 0 0 1.25em; }
+ .wrapped-source p { margin: 0 0 0 1.25em; text-indent: -1.25em; }
+ </style><style type="text/css">
+ p.notice {
+ border: 1px solid rgb(255, 0, 0);
+ background-color: rgb(238, 238, 238);
+ color: rgb(0, 51, 102);
+ padding: 0.5em;
+ margin: 1em 2em 1em 1em;
+ }
+ </style></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="../images/tomcat.gif" align="right" alt="
+ The Apache Tomcat Servlet/JSP Container
+ " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 8</font></h1><font face="arial,helvetica,sanserif">Version 8.0.0-dev, Dec 5 2012</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="../images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap class="noPrint"><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><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</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">Executo
r</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="globalresources.html">Global Resources</a></li><li><a href="jar-scanner.html">JarScanner</a></li><li><a href="listeners.html">Listeners</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/M
embership</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="cluster-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>Other</strong></p><ul><li><a href="filter.html">Filter</a></li><li><a href="systemprops.html">System properties</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>The Resources Component</h1><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><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 border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p>The <strong>Resources</strong> element represents all the resources
+ available to the web application. This includes classes, JAR files, HTML, JSPs
+ and any other files that contribute to the web application. Implementations
+ are provided to use directories, JAR files and WARs as the source of these
+ resources and the resources implementation may be extended to provide support
+ for files stored in other forms such as in a database or a versioned
+ repository.</p>
+
+ <p>Resources are cached by default. Caching may be controlled by configuring
+ the appropriate caching attributes on the containing <a href="context.html">
+ Context</a>.</p>
+
+ <p><strong>Note: Running a webapp with non-filesystem based
+ Resources implementations is only possible when the webapp does not
+ rely on direct filesystem access to its own resources, and uses the methods
+ in the ServletContext interface to access them.</strong></p>
+
+ <p>A Resources element MAY be nested inside a
+ <a href="context.html">Context</a> component. If it is not included,
+ a default filesystem based Resources will be created automatically,
+ which is sufficient for most requirements.</p>
+
+</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
+
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><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>Resources</strong>
+ support the following attributes:</p>
+
+ <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">className</code></td><td align="left" valign="center">
+ <p>Java class name of the implementation to use. This class must
+ implement the <code>org.apache.catalina.WebResourceRoot</code>
+ interface. If not specified, the standard value (defined below) will be
+ used.</p>
+ </td></tr></table>
+
+ </blockquote></td></tr></table>
+
+
+ <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><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>Resources</strong> is
+ <strong>org.apache.catalina.webresources.StandardRoot</strong>, and
+ is configured by its parent Context element.</p>
+
+ </blockquote></td></tr></table>
+
+</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Nested Components"><!--()--></a><a name="Nested_Components"><strong>Nested Components</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p>A web application's main resources are defined by the
+ <strong>docBase</strong> defined for the <a href="context.html">Context</a>.
+ Additional resources may be made available to the web application by defining
+ one or more nested components.</p>
+
+ <h3>PreResources</h3>
+
+ <p>PreResources are searched before the main resources. They will be searched
+ in the order they are defined. To configure PreResources, nest a
+ <PreResources> element inside the <Resources> element with the
+ following attributes:</p>
+
+ <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><strong><code class="attributeName">base</code></strong></td><td align="left" valign="center">
+ <p>Identifies where the resources to be used are located. This attribute
+ is required by the <code>org.apache.catalina.WebResourceSet</code>
+ implementations provided by Tomcat and should specify the absolute path to
+ the file, directory or JAR where the resources are located. Custom
+ implementations may not require it.</p>
+ </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">className</code></strong></td><td align="left" valign="center">
+ <p>Java class name of the implementation to use. This class must
+ implement the <code>org.apache.catalina.WebResourceSet</code> interface.
+ Tomcat provides three standard implementations:
+ <code>org.apache.catalina.webresources.DirResourceSet</code>,
+ <code>org.apache.catalina.webresources.FileResourceSet</code> and
+ <code>org.apache.catalina.webresources.JarResourceSet</code>. Custom
+ implementations may also be used.
+ </p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">internalPath</code></td><td align="left" valign="center">
+ <p>Identifies the path within the <strong>base</strong> where the
+ resources are to be found. This is typically only used with JAR files when
+ the resources are not located at the root of the JAR as is the case with
+ resource JARs. This attribute is required by the
+ <code>org.apache.catalina.WebResourceSet</code> implementations provided
+ by Tomcat. Custom implementations may not require it. If not specified,
+ the default value of the empty string will be used.</p>
+ </td></tr><tr><td align="left" valign="center"><code class="attributeName">webAppMount</code></td><td align="left" valign="center">
+ <p>Identifies the path within the web application that these resources
+ will be made available. This attribute is required by the
+ <code>org.apache.catalina.WebResourceSet</code> implementations provided
+ by Tomcat. Custom implementations may not require it. If not specified,
+ the default value of the empty string will be used.</p>
+ </td></tr></table>
+
+ <h3>JAR resources</h3>
+
+ <p>JarResources are searched after the main resources but before the
+ PostResources. They will be searched in the order they are defined. To
+ configure JarResources, nest a <JarResources> element inside the
+ <Resources> element. The configuration attributes are the same as for
+ <strong>PreResources</strong>.
+ </p>
+
+ <h3>Post-resources</h3>
+
+ <p>PostResources are searched after the resource JARs. They will be searched
+ in the order they are defined. To configure PostResources, nest a
+ <PostResources> element inside the <Resources> element. The
+ configuration attributes are the same as for <strong>PreResources</strong>.
+ </p>
+
+</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Special Features"><!--()--></a><a name="Special_Features"><strong>Special Features</strong></a></font></td></tr><tr><td><blockquote>
+
+ <p>No special features are associated with a <strong>Resources</strong>
+ element.</p>
+
+</blockquote></td></tr></table></td></tr><tr class="noPrint"><td width="20%" valign="top" nowrap class="noPrint"></td><td width="80%" valign="top" align="left"><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="comments_section" id="comments_section"><strong>Comments</strong></a></font></td></tr><tr><td><blockquote><p class="notice"><strong>Notice: </strong>This is not a Q&A section.
+ The Apache Comments System is explained
+ <a href="/tomcat-8.0-doc/comments.html">here</a>.
+ Comments should be pointed towards suggestions on improving the documentation
+ or server, and may be removed again by our moderators if they are either
+ implemented or considered invalid/off-topic.
+ Questions on how to manage Apache Tomcat should be directed
+ to our <a href="http://tomcat.apache.org/lists.html">mailing lists</a>.</p><script type="text/javascript"><!--//--><![CDATA[//><!--
+ var comments_shortname = 'tomcat';
+ var comments_identifier = 'http://tomcat.apache.org/tomcat-8.0-doc/config/resources.html';
+ (function(w, d) {
+ if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
+ d.write('<div id="comments_thread"><\/div>');
+ var s = d.createElement('script');
+ s.type = 'text/javascript';
+ s.async = true;
+ s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
+ (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
+ }
+ else {
+ d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.</strong><\/div>');
+ }
+ })(window, document);
+ //--><!]]></script></blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
+ Copyright © 1999-2012, Apache Software Foundation
+ </em></font></div></td></tr></table></body></html>
\ No newline at end of file
Propchange: tomcat/site/trunk/docs/tomcat-8.0-doc/config/resources.html
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: tomcat/site/trunk/docs/tomcat-8.0-doc/config/resources.html
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org