Author: markt
Date: Thu Dec 10 21:08:10 2009
New Revision: 889424
URL: http://svn.apache.org/viewvc?rev=889424&view=rev
Log:
Fix https://issues.apache.org/bugzilla/show_bug.cgi?id=47507
Document the UserDatabaseRealm, in particular the readonly attribute of
UserDartabase resources.
Modified:
tomcat/tc5.5.x/trunk/container/webapps/docs/config/realm.xml
tomcat/tc5.5.x/trunk/container/webapps/docs/jndi-resources-howto.xml
tomcat/tc5.5.x/trunk/container/webapps/docs/realm-howto.xml
Modified: tomcat/tc5.5.x/trunk/container/webapps/docs/config/realm.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc5.5.x/trunk/container/webapps/docs/config/realm.xml?rev=889424&r1=889423&r2=889424&view=diff
==============================================================================
--- tomcat/tc5.5.x/trunk/container/webapps/docs/config/realm.xml (original)
+++ tomcat/tc5.5.x/trunk/container/webapps/docs/config/realm.xml Thu Dec 10
21:08:10 2009
@@ -457,6 +457,31 @@
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>
+
+ <attributes>
+
+ <attribute name="resourceName" required="true">
+ <p>The name of the resource that this realm will use for user, password
+ and role information.</p>
+ </attribute>
+
+ </attributes>
+
+ <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
Modified: tomcat/tc5.5.x/trunk/container/webapps/docs/jndi-resources-howto.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc5.5.x/trunk/container/webapps/docs/jndi-resources-howto.xml?rev=889424&r1=889423&r2=889424&view=diff
==============================================================================
--- tomcat/tc5.5.x/trunk/container/webapps/docs/jndi-resources-howto.xml
(original)
+++ tomcat/tc5.5.x/trunk/container/webapps/docs/jndi-resources-howto.xml Thu
Dec 10 21:08:10 2009
@@ -305,6 +305,71 @@
</subsection>
+ <subsection name="UserDatabase Resources">
+
+ <h3>0. Introduction</h3>
+
+ <p>UserDatabase resources are typically configured as global resources for
+ use by a UserDatabase realm. Tomcat includes a UserDatabaseFactoory that
+ creates UserDatabase resources backed by an XML file - usually
+ <code>tomcat-users.xml</code></p>
+
+ <p>The steps required to set up a global UserDatabase resource are
described
+ below.</p>
+
+ <h3>1. Create/edit the XML file</h3>
+
+ <p>The XMl file is typically located at
+ <code>$CATALINA_BASE/conf/tomcat-users.xml</code> however, you are free to
+ locate the file anywhere on the file system. It is recommended that the XML
+ files are placed in <code>$CATALINA_BASE/conf</code>. A typical XML would
+ look like:</p>
+
+<source>
+<?xml version='1.0' encoding='utf-8'?>
+<tomcat-users>
+ <role rolename="tomcat"/>
+ <role rolename="role1"/>
+ <user username="tomcat" password="tomcat" roles="tomcat"/>
+ <user username="both" password="tomcat" roles="tomcat,role1"/>
+ <user username="role1" password="tomcat" roles="role1"/>
+</tomcat-users>
+</source>
+
+ <h3>2. Declare Your Resource</h3>
+
+ <p>Next, modify <code>$CATALINA_BASE/conf/server.xml</code> to create the
+ UserDatabase resource based on your XMl file. It should look something like
+ this:</p>
+
+<source>
+<Resource name="UserDatabase"
+ auth="Container"
+ type="org.apache.catalina.UserDatabase"
+ description="User database that can be updated and saved"
+ factory="org.apache.catalina.users.MemoryUserDatabaseFactory"
+ pathname="conf/tomcat-users.xml"
+ readonly="false" />
+</source>
+
+ <p>The <code>pathname</code> attribute can be absolute or relative. If
+ relative, it is relative to <code>$CATALINA_BASE</code>.</p>
+
+ <p>The <code>readonly</code> attribute is optional and defaults to
+ <code>false</code> if not supplied. If the XML is writeable then it will be
+ written to when Tomcat starts. <strong>WARNING:</strong> When the file is
+ written it will inherit the default file permissions for the user Tomcat
+ is running as. Ensure that these are appropriate to maintain the security
+ of your installation.</p>
+
+ <h3>3. Configure the Realm</h3>
+
+ <p>Configure a UserDatabase Realm to use this resource as described in the
+ <a href="config/realm.html">Realm configuration documentation</a>.</p>
+
+ </subsection>
+
+
<subsection name="JavaMail Sessions">
<h3>0. Introduction</h3>
Modified: tomcat/tc5.5.x/trunk/container/webapps/docs/realm-howto.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc5.5.x/trunk/container/webapps/docs/realm-howto.xml?rev=889424&r1=889423&r2=889424&view=diff
==============================================================================
--- tomcat/tc5.5.x/trunk/container/webapps/docs/realm-howto.xml (original)
+++ tomcat/tc5.5.x/trunk/container/webapps/docs/realm-howto.xml Thu Dec 10
21:08:10 2009
@@ -53,6 +53,7 @@
<a href="#JDBCRealm">JDBCRealm</a><br />
<a href="#DataSourceRealm">DataSourceRealm</a><br />
<a href="#JNDIRealm">JNDIRealm</a><br />
+<a href="#UserDatabaseRealm">UserDatabaseRealm</a><br />
<a href="#MemoryRealm">MemoryRealm</a><br />
<a href="#JAASRealm">JAASRealm</a><br />
<a href="#UserDatabaseRealm">UserDatabaseRealm</a><br />
@@ -118,6 +119,9 @@
<li><a href="#JNDIRealm">JNDIRealm</a> - Accesses authentication information
stored in an LDAP based directory server, accessed via a JNDI provider.
</li>
+<li><a href="#UserDatabaseRealm">UserDatabaseRealm</a> - Accesses
authentication
+ information stored in an UserDatabase JNDI resource, which is typically
+ backed by an XML document (<code>conf/tomcat-users.xml</code>).</li>
<li><a href="#MemoryRealm">MemoryRealm</a> - Accesses authentication
information stored in an in-memory object collection, which is initialized
from an XML document (<code>conf/tomcat-users.xml</code>).</li>
@@ -261,7 +265,7 @@
point your browser at
<a
href="http://localhost:8080/jsp-examples/security/protected/";>http://localhost:8080/jsp-examples/security/protected/</a>
and log on with one of the usernames and passwords described for the default
-<a href="#MemoryRealm">MemoryRealm</a>.</p>
+<a href="#UserDatabaseRealm">UserDatabaseRealm</a>.</p>
</subsection>
@@ -910,6 +914,71 @@
</subsection>
+<subsection name="UserDatabaseRealm">
+
+<h3>Introduction</h3>
+
+<p><strong>UserDatabaseRealm</strong> is an implementation of the Tomcat 6
+<code>Realm</code> interface that uses a JNDI resource to store user
+information. By default, the JNDI resource is backed by an XML file. It is not
+designed for large-scale production use. At startup time, the UserDatabaseRealm
+loads information about all users, and their corresponding roles, from an XML
+document (by default, this document is loaded from
+<code>$CATALINA_BASE/conf/tomcat-users.xml</code>). The users, their passwords
+and their roles may all be editing dynamically, typically via JMX. Changes may
+be saved and will be reflected in the XMl file.</p>
+
+<h3>Realm Element Attributes</h3>
+
+<p>To configure UserDatabaseRealm, you will create a <code><Realm></code>
+element and nest it in your <code>$CATALINA_BASE/conf/server.xml</code> file,
+as described <a href="#Configuring a Realm">above</a>. The attributes for the
+UserDatabaseRealm are defined in the <a href="config/realm.html">Realm</a>
+configuration documentation.</p>
+
+<h3>User File Format</h3>
+
+<p>The users file uses the same format as the
+<a href="#MemoryRealm">MemoryRealm</a>.</p>
+
+<h3>Example</h3>
+
+<p>The default installation of Tomcat 5 is configured with a UserDatabaseRealm
+nested inside the <code><Engine></code> element, so that it applies
+to all virtual hosts and web applications. The default contents of the
+<code>conf/tomcat-users.xml</code> file is:</p>
+<source>
+<tomcat-users>
+ <user name="tomcat" password="tomcat" roles="tomcat" />
+ <user name="role1" password="tomcat" roles="role1" />
+ <user name="both" password="tomcat" roles="tomcat,role1" />
+</tomcat-users>
+</source>
+
+<h3>Additional Notes</h3>
+
+<p>UserDatabaseRealm operates according to the following rules:</p>
+<ul>
+<li>When Tomcat first starts up, it loads all defined users and their
+ associated information from the users file. Changes made to the data in
+ this file will <strong>not</strong> be recognized until Tomcat is
+ restarted. Changes may be made via the UserDatabase resource. Tomcat
+ provides MBeans that may be accessed via JMX for this purpose.</li>
+<li>When a user attempts to access a protected resource for the first time,
+ Tomcat 5 will call the <code>authenticate()</code> method of this
+ <code>Realm</code>.</li>
+<li>Once a user has been authenticated, the user (and his or her associated
+ roles) are cached within Tomcat for the duration of the user's login.
+ (For FORM-based authentication, that means until the session times out or
+ is invalidated; for BASIC authentication, that means until the user
+ closes their browser). The cached user is <strong>not</strong> saved and
+ restored across sessions serialisations.</li>
+</ul>
+
+
+</subsection>
+
+
<subsection name="MemoryRealm">
<h3>Introduction</h3>
@@ -917,7 +986,8 @@
<p><strong>MemoryRealm</strong> is a simple demonstration implementation of the
Tomcat 5 <code>Realm</code> interface. It is not designed for production use.
At startup time, MemoryRealm loads information about all users, and their
-corresponding roles, from an XML document (by default, this document is loaded
from <code>$CATALINA_HOME/conf/tomcat-users.xml</code>). Changes to the data
+corresponding roles, from an XML document (by default, this document is loaded
+from <code>$CATALINA_HOME/conf/tomcat-users.xml</code>). Changes to the data
in this file are not recognized until Tomcat is restarted.</p>
<h3>Realm Element Attributes</h3>
@@ -944,18 +1014,6 @@
associated with this user.</li>
</ul>
-<h3>Example</h3>
-
-<p>The default contents of the
-<code>conf/tomcat-users.xml</code> file is:</p>
-<source>
-<tomcat-users>
- <user name="tomcat" password="tomcat" roles="tomcat" />
- <user name="role1" password="tomcat" roles="role1" />
- <user name="both" password="tomcat" roles="tomcat,role1" />
-</tomcat-users>
-</source>
-
<h3>Additional Notes</h3>
<p>MemoryRealm operates according to the following rules:</p>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
