Author: markt
Date: Thu May 19 09:43:59 2011
New Revision: 1124644
URL: http://svn.apache.org/viewvc?rev=1124644&view=rev
Log:
Fix https://issues.apache.org/bugzilla/show_bug.cgi?id=51182
Better organisation of listeners doc
Add JAAS/JMX listener info
Patch provided by Neil Laurance
Modified:
tomcat/trunk/webapps/docs/changelog.xml
tomcat/trunk/webapps/docs/config/listeners.xml
Modified: tomcat/trunk/webapps/docs/changelog.xml
URL:
http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/changelog.xml?rev=1124644&r1=1124643&r2=1124644&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/changelog.xml (original)
+++ tomcat/trunk/webapps/docs/changelog.xml Thu May 19 09:43:59 2011
@@ -76,6 +76,10 @@
Add documentation for AJP-NIO connector. (markt/rjung)
</add>
<fix>
+ <bug>51182</bug>: Document JAAS supported added in <bug>51119</bug>.
+ Patch provided by Neil Laurance. (markt)
+ </fix>
+ <fix>
<bug>51225</bug>: Fix broken documentation links for non-English
locales
in the HTML Manager application. Patch provided by Eiji Takahashi.
(markt)
Modified: tomcat/trunk/webapps/docs/config/listeners.xml
URL:
http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/config/listeners.xml?rev=1124644&r1=1124643&r2=1124644&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/config/listeners.xml (original)
+++ tomcat/trunk/webapps/docs/config/listeners.xml Thu May 19 09:43:59 2011
@@ -65,14 +65,22 @@
</subsection>
- <subsection name="Standard Implementation">
+</section>
- <p>Unlike most Catalina components, there are several standard
- <strong>Listener</strong> implementations available. As a result,
- the <code>className</code> attribute MUST be used to select the
- implementation you wish to use.</p>
+<section name="Nested Components">
- <h3>APR Lifecycle Listener
(org.apache.catalina.core.AprLifecycleListener)</h3>
+ <p>No element may be nested inside a <strong>Listener</strong>.</p>
+
+</section>
+
+<section name="Standard Implementations">
+
+ <p>Unlike most Catalina components, there are several standard
+ <strong>Listener</strong> implementations available. As a result,
+ the <code>className</code> attribute MUST be used to select the
+ implementation you wish to use.</p>
+
+ <subsection name="APR Lifecycle Listener
(org.apache.catalina.core.AprLifecycleListener)">
<p>The <strong>APR Lifecycle Listener</strong> checks for the presence of
the APR/native library and loads the library if it is present. For more
@@ -104,7 +112,9 @@
</attributes>
- <h3>Jasper Listener (org.apache.catalina.core.JasperListener)</h3>
+ </subsection>
+
+ <subsection name="Jasper Listener (org.apache.catalina.core.JasperListener)">
<p>The <strong>Jasper Listener</strong> initializes the Jasper 2 JSP engine
before any web applications that may use it are loaded. For more
@@ -117,8 +127,10 @@
<p>No additional attributes are supported by the <strong>Jasper Listener
</strong>.</p>
- <h3>Global Resources Lifecycle Listener
- (org.apache.catalina.mbeans.GlobalResourcesLifecycleListener)</h3>
+ </subsection>
+
+ <subsection name="Global Resources Lifecycle Listener
+ (org.apache.catalina.mbeans.GlobalResourcesLifecycleListener)">
<p>The <strong>Global Resources Lifecycle Listener</strong> initializes the
Global JNDI resources defined in server.xml as part of the <a
@@ -131,85 +143,10 @@
<p>No additional attributes are supported by the <strong>Global Resources
Lifecycle Listener</strong>.</p>
- <h3>JMX Remote Lifecycle Listener
- (org.apache.catalina.mbeans.JmxRemoteLifecycleListener)</h3>
-
- <p>This listener requires <code>catalina-jmx-remote.jar</code> to be placed
- in <code>$CATALINA_HOME/lib</code>. This jar may be found in the extras
- directory of the binary download area.</p>
-
- <p>The <strong>JMX Remote Lifecycle Listener</strong> fixes the ports used
by
- the JMX/RMI Server making things much simpler if you need to connect
- jconsole or a similar tool to a remote Tomcat instance that is running
- behind a firewall. Only these ports are configured via the listener. The
- remainder of the configuration is via the standard system properties for
- configuring JMX. For further information on configuring JMX see
- <a
href="http://java.sun.com/javase/6/docs/technotes/guides/management/agent.html";>
- Monitoring and Management Using JMX</a> included with the Java SDK
- documentation.</p>
-
- <p>If this listener was configured in server.xml as:
-<source>
-<Listener className="org.apache.catalina.mbeans.JmxRemoteLifecycleListener"
- rmiRegistryPortPlatform="10001" rmiServerPortPlatform="10002" />
-</source>
- with the following system properties set (e.g. in setenv.sh):
-<source>
--Dcom.sun.management.jmxremote.password.file=$CATALINA_BASE/conf/jmxremote.password
--Dcom.sun.management.jmxremote.access.file=$CATALINA_BASE/conf/jmxremote.access
--Dcom.sun.management.jmxremote.ssl=false
-</source>
- $CATALINA_BASE/conf/jmxremote.password containing:
-<source>
-admin letmein
-</source>
- $CATALINA_BASE/conf/jmxremote.access containing:
-<source>
-admin readwrite
-</source>
- then opening ports 10001 (RMI Registry) and 10002 (JMX/RMI Server) in your
- firewall would enable jconsole to connect to a Tomcat instance running
- behind a firewall using a connection string of the form:
-<source>
-service:jmx:rmi://<hostname>:10002/jndi/rmi://<hostname>:10001/jmxrmi
-</source>
- with a user name of <code>admin</code> and a password of
- <code>letmein</code>.
- </p>
-
- <p><strong>Note that the example above does not use SSL. JMX access should
- be considered equivalent to administrative access and secured accordingly.
- </strong></p>
-
- <p>This listener must only be nested within a <a
href="server.html">Server</a>
- element.</p>
-
- <p>The following additional attributes are supported by the <strong>JMX
Remote
- Lifecycle Listener</strong>:</p>
-
- <attributes>
-
- <attribute name="rmiRegistryPortPlatform" required="true">
- <p>The port to be used by the JMX/RMI registry for the Platform MBeans.
- The replaces the use of the
- <code>com.sun.management.jmxremote.port</code> system property that
- should not be set when using this valve.</p>
- </attribute>
-
- <attribute name="rmiServerPortPlatform" required="true">
- <p>The port to be used by the Platform JMX/RMI server.</p>
- </attribute>
-
- <attribute name="useLocalPorts" required="false">
- <p>Should any clients using these ports be forced to use local ports to
- connect to the the JMX/RMI server. This is useful when tunnelling
- connections over SSH or similar. Defaults to <code>false</code>.</p>
- </attribute>
-
- </attributes>
+ </subsection>
- <h3>JRE Memory Leak Prevention Listener
- (org.apache.catalina.core.JreMemoryLeakPreventionListener)</h3>
+ <subsection name="JRE Memory Leak Prevention Listener
+ (org.apache.catalina.core.JreMemoryLeakPreventionListener)">
<p>The <strong>JRE Memory Leak Prevention Listener</strong> provides
work-arounds for known places where the Java Runtime environment uses
@@ -310,7 +247,9 @@ service:jmx:rmi://<hostname>:10002
</attributes>
- <h3>Security Lifecycle Listener
(org.apache.catalina.security.SecurityListener)</h3>
+ </subsection>
+
+ <subsection name="Security Lifecycle Listener
(org.apache.catalina.security.SecurityListener)">
<p>The <strong>Security Lifecycle Listener</strong> performs a number of
security checks when Tomcat starts and prevents Tomcat from starting if
they
@@ -347,9 +286,116 @@ service:jmx:rmi://<hostname>:10002
</section>
-<section name="Nested Components">
+<section name="Additional Implementations">
- <p>No element may be nested inside a <strong>Listener</strong>.</p>
+ <subsection name="JMX Remote Lifecycle Listener
+ (org.apache.catalina.mbeans.JmxRemoteLifecycleListener)">
+
+ <p>This listener requires <code>catalina-jmx-remote.jar</code> to be placed
+ in <code>$CATALINA_HOME/lib</code>. This jar may be found in the extras
+ directory of the binary download area.</p>
+
+ <p>The <strong>JMX Remote Lifecycle Listener</strong> fixes the ports used
by
+ the JMX/RMI Server making things much simpler if you need to connect
+ jconsole or a similar tool to a remote Tomcat instance that is running
+ behind a firewall. Only these ports are configured via the listener. The
+ remainder of the configuration is via the standard system properties for
+ configuring JMX. For further information on configuring JMX see
+ <a
href="http://java.sun.com/javase/6/docs/technotes/guides/management/agent.html";>
+ Monitoring and Management Using JMX</a> included with the Java SDK
+ documentation.</p>
+
+ <p>This listener must only be nested within a <a
href="server.html">Server</a>
+ element.</p>
+
+ <p>The following additional attributes are supported by the <strong>JMX
Remote
+ Lifecycle Listener</strong>:</p>
+
+ <attributes>
+
+ <attribute name="rmiRegistryPortPlatform" required="true">
+ <p>The port to be used by the JMX/RMI registry for the Platform MBeans.
+ The replaces the use of the
+ <code>com.sun.management.jmxremote.port</code> system property that
+ should not be set when using this valve.</p>
+ </attribute>
+
+ <attribute name="rmiServerPortPlatform" required="true">
+ <p>The port to be used by the Platform JMX/RMI server.</p>
+ </attribute>
+
+ <attribute name="useLocalPorts" required="false">
+ <p>Should any clients using these ports be forced to use local ports to
+ connect to the the JMX/RMI server. This is useful when tunnelling
+ connections over SSH or similar. Defaults to <code>false</code>.</p>
+ </attribute>
+
+ </attributes>
+
+ <h3>Using file-based Authentication and Authorisation</h3>
+
+ <p>If this listener was configured in server.xml as:
+ <source>
+ <Listener
className="org.apache.catalina.mbeans.JmxRemoteLifecycleListener"
+ rmiRegistryPortPlatform="10001" rmiServerPortPlatform="10002" />
+ </source>
+ with the following system properties set (e.g. in setenv.sh):
+ <source>
+
-Dcom.sun.management.jmxremote.password.file=$CATALINA_BASE/conf/jmxremote.password
+
-Dcom.sun.management.jmxremote.access.file=$CATALINA_BASE/conf/jmxremote.access
+ -Dcom.sun.management.jmxremote.ssl=false
+ </source>
+ $CATALINA_BASE/conf/jmxremote.password containing:
+ <source>
+ admin letmein
+ </source>
+ $CATALINA_BASE/conf/jmxremote.access containing:
+ <source>
+ admin readwrite
+ </source>
+ then opening ports 10001 (RMI Registry) and 10002 (JMX/RMI Server) in your
+ firewall would enable jconsole to connect to a Tomcat instance running
+ behind a firewall using a connection string of the form:
+ <source>
+
service:jmx:rmi://<hostname>:10002/jndi/rmi://<hostname>:10001/jmxrmi
+ </source>
+ with a user name of <code>admin</code> and a password of
+ <code>letmein</code>.
+ </p>
+
+ <h3>Using JAAS</h3>
+
+ <p>If we use the following system properties instead:
+ <source>
+ -Dcom.sun.management.jmxremote.login.config=Tomcat
+ -Djava.security.auth.login.config=$CATALINA_BASE/conf/login.config
+
-Dcom.sun.management.jmxremote.access.file=$CATALINA_BASE/conf/jmxremote.access
+ -Dcom.sun.management.jmxremote.ssl=false
+ </source>
+ $CATALINA_BASE/conf/login.config containing your choice of JAAS
LoginModule implementation, for example:
+ <source>
+ Tomcat { /* should match to the com.sun.management.jmxremote.login.config
property */
+
+ /* for illustration purposes only */
+ com.sun.security.auth.module.LdapLoginModule REQUIRED
+ userProvider="ldap://ldap-svr/ou=people,dc=example,dc=com";
+ userFilter="(&(uid={USERNAME})(objectClass=inetOrgPerson))"
+ authzIdentity="admin"
+ debug=true;
+ };
+ </source>
+ $CATALINA_BASE/conf/jmxremote.access containing:
+ <source>
+ admin readwrite
+ </source>
+ then we would need to provide LDAP credentials instead.
+ </p>
+
+ <p><strong>Note that the examples above do not use SSL. JMX access should
+ be considered equivalent to administrative access and secured accordingly.
+ </strong></p>
+
+ </subsection>
</section>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
