From e2f3fb77eafca1157472525df65b0bbdef6de76d Mon Sep 17 00:00:00 2001 From: markt Date: Thu, 19 May 2011 09:43:59 +0000 Subject: [PATCH] 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 git-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@1124644 13f79535-47bb-0310-9956-ffa450edef68 --- webapps/docs/changelog.xml | 4 + webapps/docs/config/listeners.xml | 226 +++++++++++++++++++++++--------------- 2 files changed, 140 insertions(+), 90 deletions(-) diff --git a/webapps/docs/changelog.xml b/webapps/docs/changelog.xml index 1ed33a903..0f9e8471b 100644 --- a/webapps/docs/changelog.xml +++ b/webapps/docs/changelog.xml @@ -76,6 +76,10 @@ Add documentation for AJP-NIO connector. (markt/rjung) + 51182: Document JAAS supported added in 51119. + Patch provided by Neil Laurance. (markt) + + 51225: Fix broken documentation links for non-English locales in the HTML Manager application. Patch provided by Eiji Takahashi. (markt) diff --git a/webapps/docs/config/listeners.xml b/webapps/docs/config/listeners.xml index 71dd84d56..8b50f6147 100644 --- a/webapps/docs/config/listeners.xml +++ b/webapps/docs/config/listeners.xml @@ -65,14 +65,22 @@ - + -

Unlike most Catalina components, there are several standard - Listener implementations available. As a result, - the className attribute MUST be used to select the - implementation you wish to use.

+
-

APR Lifecycle Listener (org.apache.catalina.core.AprLifecycleListener)

+

No element may be nested inside a Listener.

+ +
+ +
+ +

Unlike most Catalina components, there are several standard + Listener implementations available. As a result, + the className attribute MUST be used to select the + implementation you wish to use.

+ +

The APR Lifecycle Listener checks for the presence of the APR/native library and loads the library if it is present. For more @@ -104,7 +112,9 @@ -

Jasper Listener (org.apache.catalina.core.JasperListener)

+ + +

The Jasper Listener initializes the Jasper 2 JSP engine before any web applications that may use it are loaded. For more @@ -117,8 +127,10 @@

No additional attributes are supported by the Jasper Listener .

-

Global Resources Lifecycle Listener - (org.apache.catalina.mbeans.GlobalResourcesLifecycleListener)

+ + +

The Global Resources Lifecycle Listener initializes the Global JNDI resources defined in server.xml as part of the No additional attributes are supported by the Global Resources Lifecycle Listener.

-

JMX Remote Lifecycle Listener - (org.apache.catalina.mbeans.JmxRemoteLifecycleListener)

- -

This listener requires catalina-jmx-remote.jar to be placed - in $CATALINA_HOME/lib. This jar may be found in the extras - directory of the binary download area.

- -

The JMX Remote Lifecycle Listener 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 - - Monitoring and Management Using JMX included with the Java SDK - documentation.

- -

If this listener was configured in server.xml as: - -<Listener className="org.apache.catalina.mbeans.JmxRemoteLifecycleListener" - rmiRegistryPortPlatform="10001" rmiServerPortPlatform="10002" /> - - with the following system properties set (e.g. in setenv.sh): - --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 - - $CATALINA_BASE/conf/jmxremote.password containing: - -admin letmein - - $CATALINA_BASE/conf/jmxremote.access containing: - -admin readwrite - - 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: - -service:jmx:rmi://<hostname>:10002/jndi/rmi://<hostname>:10001/jmxrmi - - with a user name of admin and a password of - letmein. -

- -

Note that the example above does not use SSL. JMX access should - be considered equivalent to administrative access and secured accordingly. -

- -

This listener must only be nested within a Server - element.

- -

The following additional attributes are supported by the JMX Remote - Lifecycle Listener:

- - - - -

The port to be used by the JMX/RMI registry for the Platform MBeans. - The replaces the use of the - com.sun.management.jmxremote.port system property that - should not be set when using this valve.

- - - -

The port to be used by the Platform JMX/RMI server.

- - - -

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 false.

- - - + -

JRE Memory Leak Prevention Listener - (org.apache.catalina.core.JreMemoryLeakPreventionListener)

+

The JRE Memory Leak Prevention Listener provides work-arounds for known places where the Java Runtime environment uses @@ -310,7 +247,9 @@ service:jmx:rmi://<hostname>:10002/jndi/rmi://<hostname>:10001/jmxrm -

Security Lifecycle Listener (org.apache.catalina.security.SecurityListener)

+ + +

The Security Lifecycle Listener 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/jndi/rmi://<hostname>:10001/jmxrm

-
+
-

No element may be nested inside a Listener.

+ + +

This listener requires catalina-jmx-remote.jar to be placed + in $CATALINA_HOME/lib. This jar may be found in the extras + directory of the binary download area.

+ +

The JMX Remote Lifecycle Listener 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 + + Monitoring and Management Using JMX included with the Java SDK + documentation.

+ +

This listener must only be nested within a Server + element.

+ +

The following additional attributes are supported by the JMX Remote + Lifecycle Listener:

+ + + + +

The port to be used by the JMX/RMI registry for the Platform MBeans. + The replaces the use of the + com.sun.management.jmxremote.port system property that + should not be set when using this valve.

+ + + +

The port to be used by the Platform JMX/RMI server.

+ + + +

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 false.

+ + + + +

Using file-based Authentication and Authorisation

+ +

If this listener was configured in server.xml as: + + <Listener className="org.apache.catalina.mbeans.JmxRemoteLifecycleListener" + rmiRegistryPortPlatform="10001" rmiServerPortPlatform="10002" /> + + with the following system properties set (e.g. in setenv.sh): + + -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 + + $CATALINA_BASE/conf/jmxremote.password containing: + + admin letmein + + $CATALINA_BASE/conf/jmxremote.access containing: + + admin readwrite + + 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: + + service:jmx:rmi://<hostname>:10002/jndi/rmi://<hostname>:10001/jmxrmi + + with a user name of admin and a password of + letmein. +

+ +

Using JAAS

+ +

If we use the following system properties instead: + + -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 + + $CATALINA_BASE/conf/login.config containing your choice of JAAS LoginModule implementation, for example: + + 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; + }; + + $CATALINA_BASE/conf/jmxremote.access containing: + + admin readwrite + + then we would need to provide LDAP credentials instead. +

+ +

Note that the examples above do not use SSL. JMX access should + be considered equivalent to administrative access and secured accordingly. +

+ +
-- 2.11.0