Author: markt
Date: Thu Dec 10 20:37:28 2009
New Revision: 889419
URL: http://svn.apache.org/viewvc?rev=889419&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/tc6.0.x/trunk/ (props changed)
tomcat/tc6.0.x/trunk/webapps/docs/config/realm.xml
tomcat/tc6.0.x/trunk/webapps/docs/jndi-resources-howto.xml
tomcat/tc6.0.x/trunk/webapps/docs/realm-howto.xml
Propchange: tomcat/tc6.0.x/trunk/
------------------------------------------------------------------------------
--- svn:mergeinfo (original)
+++ svn:mergeinfo Thu Dec 10 20:37:28 2009
@@ -1 +1 @@
-/tomcat/trunk:601180,606992,612607,630314,640888,652744,653247,666232,673796,673820,677910,683969,683982,684001,684081,684234,684269-684270,685177,687503,687645,689402,690781,691392,691805,692748,693378,694992,695053,695311,696780,696782,698012,698227,698236,698613,699427,699634,701355,709294,709811,709816,710063,710066,710125,710205,711126,711600,712461,712467,713953,714002,718360,719119,719124,719602,719626,719628,720046,720069,721040,721286,721708,721886,723404,723738,726052,727303,728032,728768,728947,729057,729567,729569,729571,729681,729809,729815,729934,730250,730590,731651,732859,732863,734734,740675,740684,742677,742697,742714,744160,744238,746321,746384,746425,747834,747863,748344,750258,750291,750921,751286-751287,751289,751295,753039,757335,757774,758365,758596,758616,758664,759074,761601,762868,762929,762936-762937,763166,763183,763193,763228,763262,763298,763302,763325,763599,763611,763654,763681,763706,764985,764997,765662,768335,769979,770716,770809,770876,77
2872,776921,776924,776935,776945,777464,777466,777576,777625,778379,778523-778524,781528,781779,782145,782791,783316,783696,783724,783756,783762,783766,783863,783934,784453,784602,784614,785381,785688,785768,785859,786468,786487,786490,786496,786667,787627,787770,787985,789389,790405,791041,791184,791194,791224,791243,791326,791328,791789,792740,793372,793757,793882,793981,794082,794673,794822,795043,795152,795210,795457,795466,797168,797425,797596,797607,802727,802940,804462,804544,804734,805153,809131,809603,810916,810977,812125,812137,812432,813001,813013,813866,814180,814708,814876,815972,817442,817822,819339,819361,820110,820132,820874,820954,821397,828196,828201,828210,828225,828759,830378-830379,831106,831774,831785,831828,831850,831860,832218,833121,833545,834047,835036,835336
+/tomcat/trunk:601180,606992,612607,630314,640888,652744,653247,666232,673796,673820,677910,683969,683982,684001,684081,684234,684269-684270,685177,687503,687645,689402,690781,691392,691805,692748,693378,694992,695053,695311,696780,696782,698012,698227,698236,698613,699427,699634,701355,709294,709811,709816,710063,710066,710125,710205,711126,711600,712461,712467,713953,714002,718360,719119,719124,719602,719626,719628,720046,720069,721040,721286,721708,721886,723404,723738,726052,727303,728032,728768,728947,729057,729567,729569,729571,729681,729809,729815,729934,730250,730590,731651,732859,732863,734734,740675,740684,742677,742697,742714,744160,744238,746321,746384,746425,747834,747863,748344,750258,750291,750921,751286-751287,751289,751295,753039,757335,757774,758365,758596,758616,758664,759074,761601,762868,762929,762936-762937,763166,763183,763193,763228,763262,763298,763302,763325,763599,763611,763654,763681,763706,764985,764997,765662,768335,769979,770716,770809,770876,77
2872,776921,776924,776935,776945,777464,777466,777576,777625,778379,778523-778524,781528,781779,782145,782791,783316,783696,783724,783756,783762,783766,783863,783934,784453,784602,784614,785381,785688,785768,785859,786468,786487,786490,786496,786667,787627,787770,787985,789389,790405,791041,791184,791194,791224,791243,791326,791328,791789,792740,793372,793757,793882,793981,794082,794673,794822,795043,795152,795210,795457,795466,797168,797425,797596,797607,802727,802940,804462,804544,804734,805153,809131,809603,810916,810977,812125,812137,812432,813001,813013,813866,814180,814708,814876,815972,817442,817822,819339,819361,820110,820132,820874,820954,821397,828196,828201,828210,828225,828759,830378-830379,831106,831774,831785,831828,831850,831860,832218,833121,833545,834047,835036,835336,889363
Modified: tomcat/tc6.0.x/trunk/webapps/docs/config/realm.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/config/realm.xml?rev=889419&r1=889418&r2=889419&view=diff
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/config/realm.xml (original)
+++ tomcat/tc6.0.x/trunk/webapps/docs/config/realm.xml Thu Dec 10 20:37:28 2009
@@ -477,6 +477,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/tc6.0.x/trunk/webapps/docs/jndi-resources-howto.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/jndi-resources-howto.xml?rev=889419&r1=889418&r2=889419&view=diff
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/jndi-resources-howto.xml (original)
+++ tomcat/tc6.0.x/trunk/webapps/docs/jndi-resources-howto.xml Thu Dec 10
20:37:28 2009
@@ -309,6 +309,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/tc6.0.x/trunk/webapps/docs/realm-howto.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/realm-howto.xml?rev=889419&r1=889418&r2=889419&view=diff
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/realm-howto.xml (original)
+++ tomcat/tc6.0.x/trunk/webapps/docs/realm-howto.xml Thu Dec 10 20:37:28 2009
@@ -119,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 +264,7 @@
point your browser at
<a
href="http://localhost:8080/examples/jsp/security/protected/";>http://localhost:8080/examples/jsp/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>
@@ -906,6 +909,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 6 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 6 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>
@@ -913,7 +981,8 @@
<p><strong>MemoryRealm</strong> is a simple demonstration implementation of the
Tomcat 6 <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_BASE/conf/tomcat-users.xml</code>). Changes to the data
+corresponding roles, from an XML document (by default, this document is loaded
+from <code>$CATALINA_BASE/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>
@@ -940,20 +1009,6 @@
associated with this user.</li>
</ul>
-<h3>Example</h3>
-
-<p>The default installation of Tomcat 6 is configured with a MemoryRealm
-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>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
