Author: kkolinko
Date: Wed Nov 26 00:19:50 2014
New Revision: 1641734
URL: http://svn.apache.org/r1641734
Log:
Improve documentation of the Manager application:
- Correction: The default configuration uses UserDatabaseRealm, not
MemoryRealm. Add DataSourceRealm.
- Add section on HTML interface with a link to a document. Correct URL.
- Expand explanation on CSRF feature.
Merged revision 1641723 from tomcat/tc8.0.x/trunk.
Modified:
tomcat/tc7.0.x/trunk/ (props changed)
tomcat/tc7.0.x/trunk/webapps/docs/changelog.xml
tomcat/tc7.0.x/trunk/webapps/docs/manager-howto.xml
Propchange: tomcat/tc7.0.x/trunk/
------------------------------------------------------------------------------
Merged /tomcat/trunk:r1641656-1641692
Merged /tomcat/tc8.0.x/trunk:r1641723
Modified: tomcat/tc7.0.x/trunk/webapps/docs/changelog.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc7.0.x/trunk/webapps/docs/changelog.xml?rev=1641734&r1=1641733&r2=1641734&view=diff
==============================================================================
--- tomcat/tc7.0.x/trunk/webapps/docs/changelog.xml (original)
+++ tomcat/tc7.0.x/trunk/webapps/docs/changelog.xml Wed Nov 26 00:19:50 2014
@@ -115,6 +115,9 @@
WebSocket classes with Java 7 (<code>ide-eclipse-websocket</code>
target added in 7.0.56). (kkolinko)
</update>
+ <update>
+ Improve Tomcat Manager documentation. (kkolinko)
+ </update>
</changelog>
</subsection>
<subsection name="Other">
Modified: tomcat/tc7.0.x/trunk/webapps/docs/manager-howto.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc7.0.x/trunk/webapps/docs/manager-howto.xml?rev=1641734&r1=1641733&r2=1641734&view=diff
==============================================================================
--- tomcat/tc7.0.x/trunk/webapps/docs/manager-howto.xml (original)
+++ tomcat/tc7.0.x/trunk/webapps/docs/manager-howto.xml Wed Nov 26 00:19:50 2014
@@ -83,7 +83,7 @@ example:</p>
<ul>
<li>As an application with a user interface you use in your browser.
Here is an example URL where you can replace <code>localhost</code> with
-your website host name: <code>http://localhost/manager/html/</code> .</li>
+your website host name: <code>http://localhost:8080/manager/html</code> .</li>
<li>A minimal version using HTTP requests only which is suitable for use
by scripts setup by system administrators. Commands are given as part of the
request URI, and responses are in the form of simple text that can be easily
@@ -133,22 +133,25 @@ web application. The available roles are
</ul>
<p>The HTML interface is protected against CSRF (Cross-Site Request Forgery)
-attacks, but the text and JMX interfaces cannot be protected. To maintain
+attacks, but the text and JMX interfaces cannot be protected. It means that
+users who are allowed access to the text and JMX interfaces have to be cautious
+when accessing the Manager application with a web browser.
+To maintain
the CSRF protection:</p>
<ul>
- <li>Users with the <strong>manager-gui</strong> role should not be granted
- the <strong>manager-script</strong> or <strong>manager-jmx</strong>
- roles.</li>
<li>If you use web browser to access the Manager application using
a user that has either <strong>manager-script</strong> or
<strong>manager-jmx</strong> roles (for example for testing
- the plain text or JMX interfaces),
- then all windows of the browser MUST be closed afterwards to terminate
- the session.</li>
+ the plain text or JMX interfaces), do not visit other sites
+ where you may fall victim to a CSRF attack, and you MUST close all
windows
+ of the browser afterwards to terminate the session.</li>
+ <li>It is recommended to never grant
+ the <strong>manager-script</strong> or <strong>manager-jmx</strong>
+ roles to users that have the <strong>manager-gui</strong> role.</li>
</ul>
-<p>Note that JMX proxy interface is effectively low-level root-like
+<p><strong>Note</strong> that JMX proxy interface is effectively low-level
root-like
administrative interface of Tomcat. One can do a lot, if he knows
what commands to call. You should be cautious when enabling the
<strong>manager-jmx</strong> role.</p>
@@ -162,13 +165,13 @@ As the majority of this document describ
interface, let the role name for further example to be
<strong>manager-script</strong>.
Exactly how the usernames/passwords are configured depends on which
-<code>Realm</code> implementation you are using:</p>
+<a href="config/realm.html">Realm implementation</a> you are using:</p>
<ul>
-<li><em>MemoryRealm</em> — This one is configured in the default
- <code>$CATALINA_BASE/conf/server.xml</code>.
- If you have not configured it differently, or replaced it with
- a different <code>Realm</code> implementation, this realm
- reads an XML-format file stored at
+<li><em>UserDatabaseRealm</em> plus <em>MemoryUserDatabase</em>, or
<em>MemoryRealm</em>
+ — The <em>UserDatabaseRealm</em> and <em>MemoryUserDatabase</em> are
+ configured in the default <code>$CATALINA_BASE/conf/server.xml</code>.
+ Both <em>MemoryUserDatabase</em> and <em>MemoryRealm</em> read an
+ XML-format file by default stored at
<code>$CATALINA_BASE/conf/tomcat-users.xml</code>, which can be
edited with any text editor. This file contains an XML
<code><user></code> for each individual user, which might
@@ -179,7 +182,8 @@ Exactly how the usernames/passwords are
add the <strong>manager-script</strong> role to the comma-delimited
<code>roles</code> attribute for one or more existing users, and/or
create new users with that assigned role.</li>
-<li><em>JDBCRealm</em> — Your user and role information is stored in
+<li><em>DataSourceRealm</em> or <em>JDBCRealm</em>
+ — Your user and role information is stored in
a database accessed via JDBC. Add the <strong>manager-script</strong> role
to one or more existing users, and/or create one or more new users
with this role assigned, following the standard procedures for your
@@ -210,6 +214,28 @@ an example of restricting access to the
</section>
+<section name="HTML User-friendly Interface">
+
+<p>The user-friendly HTML interface of Manager web application is located
at</p>
+
+<source>http://{host}:{port}/manager/html</source>
+
+<p>As has already been mentioned above, you need <strong>manager-gui</strong>
+role to be allowed to access it. There is a separate document that provides
+help on this interface. See:</p>
+
+<ul>
+ <li><a href="html-manager-howto.html">HTML Manager documentation</a></li>
+</ul>
+
+<p>The HTML interface is protected against CSRF (Cross-Site Request Forgery)
+attacks. Each access to the HTML pages generates a random token, which is
+stored in your session and is included in all links on the page. If your next
+action does not have correct value of the token, the action will be denied.
+If the token has expired you can start again from the main page or
+<em>List Applications</em> page of Manager.</p>
+
+</section>
<section name="Supported Manager Commands">
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
