svn commit: r1224607 - /tomcat/trunk/webapps/docs/manager-howto.xml

[kk...@apache.org]

Author: kkolinko
Date: Sun Dec 25 13:24:41 2011
New Revision: 1224607

URL: http://svn.apache.org/viewvc?rev=1224607&view=rev
Log:
Improve manager-howto.xml:
Document the list of roles that allow access to Manager webapp.
The manager-script role is just one of them.

Modified:
    tomcat/trunk/webapps/docs/manager-howto.xml

Modified: tomcat/trunk/webapps/docs/manager-howto.xml
URL: http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/manager-howto.xml?rev=1224607&r1=1224606&r2=1224607&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/manager-howto.xml (original)
+++ tomcat/trunk/webapps/docs/manager-howto.xml Sun Dec 25 13:24:41 2011
@@ -111,22 +111,62 @@ With Ant</a> for more information.</li>
 anyone on the Internet to execute the Manager application on your server.
 Therefore, the Manager application is shipped with the requirement that anyone
 who attempts to use it must authenticate themselves, using a username and
-password that have the role <strong>manager-script</strong> associated with
-them. Further, there is no username in the default users file
-(<code>$CATALINA_BASE/conf/tomcat-users.xml</code>) that is assigned this
-role.  Therefore, access to the Manager application is completely disabled
+password that have one of <strong>manager-**</strong> roles associated with
+them (the role name depends on what functionality is required).
+Further, there is no username in the default users file
+(<code>$CATALINA_BASE/conf/tomcat-users.xml</code>) that is assigned to those
+roles.  Therefore, access to the Manager application is completely disabled
 by default.</p>
 
+<p>You can find the role names in the <code>web.xml</code> file of the Manager
+web application. The available roles are:</p>
+
+<ul>
+  <li><strong>manager-gui</strong> &#8212; Access to the HTML interface.</li>
+  <li><strong>manager-status</strong> &#8212; Access to the "Server Status"
+    page in the HTML interface only.</li>
+  <li><strong>manager-script</strong> &#8212; Access to the tools-friendly
+    plain text interface, that is described in this document.</li>
+  <li><strong>manager-jmx</strong> &#8212; Access to JMX proxy interface.</li>
+</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
+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>
+</ul>
+
+<p>Note 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>
+
 <p>To enable access to the Manager web application, you must either create
-a new username/password combination and associate the role name
-<strong>manager-script</strong> with it, or add the
-<strong>manager-script</strong> role
-to some existing username/password combination.  Exactly where this is done
-depends on which <code>Realm</code> implementation you are using:</p>
+a new username/password combination and associate one of the
+<strong>manager-**</strong> roles with it, or add a
+<strong>manager-**</strong> role
+to some existing username/password combination.
+As the majority of this document describes the commands of plain textual
+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>
 <ul>
-<li><em>MemoryRealm</em> - If you have not customized your
-    <code>$CATALINA_BASE/conf/server.xml</code> to select a different one,
-    Tomcat defaults to an XML-format file stored at
+<li><em>MemoryRealm</em> &#8212; 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
     <code>$CATALINA_BASE/conf/tomcat-users.xml</code>, which can be
     edited with any text editor.  This file contains an XML
     <code>&lt;user&gt;</code> for each individual user, which might
@@ -139,12 +179,12 @@ depends on which <code>Realm</code> impl
     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>JDBCRealm</em> &#8212; 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
     environment.</li>
-<li><em>JNDIRealm</em> - Your user and role information is stored in
+<li><em>JNDIRealm</em> &#8212; Your user and role information is stored in
     a directory server accessed via LDAP.  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
@@ -158,8 +198,8 @@ as long as they identify a valid user in
 the role <strong>manager-script</strong>.</p>
 
 <p>In addition to the password restrictions the Manager web application
-could be restricted by the remote IP address or host by adding a
-<code>RemoteAddrValve</code> or <code>RemoteHostValve</code>.
+could be restricted by the <strong>remote IP address</strong> or host by adding
+a <code>RemoteAddrValve</code> or <code>RemoteHostValve</code>.
 See <a href="config/valve.html#Remote_Address_Filter">valves documentation</a>
 for details. Here is
 an example of restricting access to the localhost by IP address:</p>
@@ -170,17 +210,6 @@ an example of restricting access to the 
 &lt;/Context&gt;
 </pre>
 
-<p>The HTML interface is protected against CSRF but the text and JMX interfaces
-are not. To maintain the CSRF protection:</p>
-
-<ul>
-  <li>users with the <code>manager-gui</code> role should not be granted either the
-      <code>manager-script</code> or <code>manager-jmx</code> roles.</li>
-  <li>if the text or jmx interfaces are accessed through a browser (e.g. for
-      testing since these interfaces are intended for tools not humans) then the
-      browser must be closed afterwards to terminate the session.</li>
-</ul>
-
 </section>
 
 



---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org