View | Details | Raw Unified | Return to bug 51182
Collapse All | Expand All

(-)webapps/docs/config/listeners.xml (-90 / +136 lines)
Lines 65-79 Link Here
65
65
66
  </subsection>
66
  </subsection>
67
67
68
  <subsection name="Standard Implementation">
68
</section>
69
69
70
    <p>Unlike most Catalina components, there are several standard
70
<section name="Nested Components">
71
    <strong>Listener</strong> implementations available.  As a result,
72
    the <code>className</code> attribute MUST be used to select the
73
    implementation you wish to use.</p>
74
71
75
    <h3>APR Lifecycle Listener (org.apache.catalina.core.AprLifecycleListener)</h3>
72
  <p>No element may be nested inside a <strong>Listener</strong>.</p>
76
73
74
</section>
75
76
<section name="Standard Implementations">
77
78
  <p>Unlike most Catalina components, there are several standard
79
  <strong>Listener</strong> implementations available.  As a result,
80
  the <code>className</code> attribute MUST be used to select the
81
  implementation you wish to use.</p>
82
83
  <subsection name="APR Lifecycle Listener (org.apache.catalina.core.AprLifecycleListener)">
84
77
    <p>The <strong>APR Lifecycle Listener</strong> checks for the presence of
85
    <p>The <strong>APR Lifecycle Listener</strong> checks for the presence of
78
    the APR/native library and loads the library if it is present. For more
86
    the APR/native library and loads the library if it is present. For more
79
    information see the <a href="../apr.html">APR/native guide</a>.</p>
87
    information see the <a href="../apr.html">APR/native guide</a>.</p>
Lines 104-111 Link Here
104
112
105
    </attributes>
113
    </attributes>
106
114
107
    <h3>Jasper Listener (org.apache.catalina.core.JasperListener)</h3>
115
  </subsection>
108
116
117
  <subsection name="Jasper Listener (org.apache.catalina.core.JasperListener)">
118
109
    <p>The <strong>Jasper Listener</strong> initializes the Jasper 2 JSP engine
119
    <p>The <strong>Jasper Listener</strong> initializes the Jasper 2 JSP engine
110
    before any web applications that may use it are loaded. For more
120
    before any web applications that may use it are loaded. For more
111
    information on the Jasper 2 JSP engine see the
121
    information on the Jasper 2 JSP engine see the
Lines 117-125 Link Here
117
    <p>No additional attributes are supported by the <strong>Jasper Listener
127
    <p>No additional attributes are supported by the <strong>Jasper Listener
118
    </strong>.</p>
128
    </strong>.</p>
119
129
120
    <h3>Global Resources Lifecycle Listener
130
  </subsection>
121
    (org.apache.catalina.mbeans.GlobalResourcesLifecycleListener)</h3>
122
131
132
  <subsection name="Global Resources Lifecycle Listener
133
  (org.apache.catalina.mbeans.GlobalResourcesLifecycleListener)">
134
123
    <p>The <strong>Global Resources Lifecycle Listener</strong> initializes the
135
    <p>The <strong>Global Resources Lifecycle Listener</strong> initializes the
124
    Global JNDI resources defined in server.xml as part of the <a
136
    Global JNDI resources defined in server.xml as part of the <a
125
    href="globalresources.html">Global Resources</a> element. Without this
137
    href="globalresources.html">Global Resources</a> element. Without this
Lines 131-216 Link Here
131
    <p>No additional attributes are supported by the <strong>Global Resources
143
    <p>No additional attributes are supported by the <strong>Global Resources
132
    Lifecycle Listener</strong>.</p>
144
    Lifecycle Listener</strong>.</p>
133
145
134
    <h3>JMX Remote Lifecycle Listener
146
  </subsection>
135
    (org.apache.catalina.mbeans.JmxRemoteLifecycleListener)</h3>
136
147
137
    <p>This listener requires <code>catalina-jmx-remote.jar</code> to be placed
148
  <subsection name="JRE Memory Leak Prevention Listener
138
    in <code>$CATALINA_HOME/lib</code>. This jar may be found in the extras
149
      (org.apache.catalina.core.JreMemoryLeakPreventionListener)">
139
    directory of the binary download area.</p>
140
150
141
    <p>The <strong>JMX Remote Lifecycle Listener</strong> fixes the ports used by
142
    the JMX/RMI Server making things much simpler if you need to connect
143
    jconsole or a similar tool to a remote Tomcat instance that is running
144
    behind a firewall. Only these ports are configured via the listener. The
145
    remainder of the configuration is via the standard system properties for
146
    configuring JMX. For further information on configuring JMX see
147
    <a href="http://java.sun.com/javase/6/docs/technotes/guides/management/agent.html">
148
    Monitoring and Management Using JMX</a> included with the Java SDK
149
    documentation.</p>
150
151
    <p>If this listener was configured in server.xml as:
152
<source>
153
&lt;Listener className="org.apache.catalina.mbeans.JmxRemoteLifecycleListener"
154
          rmiRegistryPortPlatform="10001" rmiServerPortPlatform="10002" /&gt;
155
</source>
156
    with the following system properties set (e.g. in setenv.sh):
157
<source>
158
-Dcom.sun.management.jmxremote.password.file=$CATALINA_BASE/conf/jmxremote.password
159
-Dcom.sun.management.jmxremote.access.file=$CATALINA_BASE/conf/jmxremote.access
160
-Dcom.sun.management.jmxremote.ssl=false
161
</source>
162
    $CATALINA_BASE/conf/jmxremote.password containing:
163
<source>
164
admin letmein
165
</source>
166
    $CATALINA_BASE/conf/jmxremote.access containing:
167
<source>
168
admin readwrite
169
</source>
170
    then opening ports 10001 (RMI Registry) and 10002 (JMX/RMI Server) in your
171
    firewall would enable jconsole to connect to a Tomcat instance running
172
    behind a firewall using a connection string of the form:
173
<source>
174
service:jmx:rmi://&lt;hostname&gt;:10002/jndi/rmi://&lt;hostname&gt;:10001/jmxrmi
175
</source>
176
    with a user name of <code>admin</code> and a password of
177
    <code>letmein</code>.
178
    </p>
179
    
180
    <p><strong>Note that the example above does not use SSL. JMX access should
181
    be considered equivalent to administrative access and secured accordingly.
182
    </strong></p>
183
184
    <p>This listener must only be nested within a <a href="server.html">Server</a>
185
    element.</p>
186
187
    <p>The following additional attributes are supported by the <strong>JMX Remote
188
    Lifecycle Listener</strong>:</p>
189
190
    <attributes>
191
192
      <attribute name="rmiRegistryPortPlatform" required="true">
193
        <p>The port to be used by the JMX/RMI registry for the Platform MBeans.
194
        The replaces the use of the
195
        <code>com.sun.management.jmxremote.port</code> system property that
196
        should not be set when using this valve.</p>
197
      </attribute>
198
199
      <attribute name="rmiServerPortPlatform" required="true">
200
        <p>The port to be used by the Platform JMX/RMI server.</p>
201
      </attribute>
202
203
      <attribute name="useLocalPorts" required="false">
204
        <p>Should any clients using these ports be forced to use local ports to
205
        connect to the the JMX/RMI server. This is useful when tunnelling
206
        connections over SSH or similar. Defaults to <code>false</code>.</p>
207
      </attribute>
208
209
    </attributes>
210
211
    <h3>JRE Memory Leak Prevention Listener
212
        (org.apache.catalina.core.JreMemoryLeakPreventionListener)</h3>
213
214
    <p>The <strong>JRE Memory Leak Prevention Listener</strong> provides
151
    <p>The <strong>JRE Memory Leak Prevention Listener</strong> provides
215
    work-arounds for known places where the Java Runtime environment uses
152
    work-arounds for known places where the Java Runtime environment uses
216
    the context class loader to load a singleton as this will cause a memory
153
    the context class loader to load a singleton as this will cause a memory
Lines 310-317 Link Here
310
247
311
    </attributes>
248
    </attributes>
312
249
313
    <h3>Security Lifecycle Listener (org.apache.catalina.security.SecurityListener)</h3>
250
  </subsection>
314
251
252
  <subsection name="Security Lifecycle Listener (org.apache.catalina.security.SecurityListener)">
253
315
    <p>The <strong>Security Lifecycle Listener</strong> performs a number of
254
    <p>The <strong>Security Lifecycle Listener</strong> performs a number of
316
    security checks when Tomcat starts and prevents Tomcat from starting if they
255
    security checks when Tomcat starts and prevents Tomcat from starting if they
317
    fail. The listener is not enabled by default. To enabled it uncomment the
256
    fail. The listener is not enabled by default. To enabled it uncomment the
Lines 347-356 Link Here
347
286
348
</section>
287
</section>
349
288
350
<section name="Nested Components">
289
<section name="Additional Implementations">
351
290
352
  <p>No element may be nested inside a <strong>Listener</strong>.</p>
291
  <subsection name="JMX Remote Lifecycle Listener
292
  (org.apache.catalina.mbeans.JmxRemoteLifecycleListener)">
353
293
294
    <p>This listener requires <code>catalina-jmx-remote.jar</code> to be placed
295
    in <code>$CATALINA_HOME/lib</code>. This jar may be found in the extras
296
    directory of the binary download area.</p>
297
298
    <p>The <strong>JMX Remote Lifecycle Listener</strong> fixes the ports used by
299
    the JMX/RMI Server making things much simpler if you need to connect
300
    jconsole or a similar tool to a remote Tomcat instance that is running
301
    behind a firewall. Only these ports are configured via the listener. The
302
    remainder of the configuration is via the standard system properties for
303
    configuring JMX. For further information on configuring JMX see
304
    <a href="http://java.sun.com/javase/6/docs/technotes/guides/management/agent.html">
305
    Monitoring and Management Using JMX</a> included with the Java SDK
306
    documentation.</p>
307
308
    <p>This listener must only be nested within a <a href="server.html">Server</a>
309
    element.</p>
310
311
    <p>The following additional attributes are supported by the <strong>JMX Remote
312
    Lifecycle Listener</strong>:</p>
313
314
    <attributes>
315
316
      <attribute name="rmiRegistryPortPlatform" required="true">
317
        <p>The port to be used by the JMX/RMI registry for the Platform MBeans.
318
        The replaces the use of the
319
        <code>com.sun.management.jmxremote.port</code> system property that
320
        should not be set when using this valve.</p>
321
      </attribute>
322
323
      <attribute name="rmiServerPortPlatform" required="true">
324
        <p>The port to be used by the Platform JMX/RMI server.</p>
325
      </attribute>
326
327
      <attribute name="useLocalPorts" required="false">
328
        <p>Should any clients using these ports be forced to use local ports to
329
        connect to the the JMX/RMI server. This is useful when tunnelling
330
        connections over SSH or similar. Defaults to <code>false</code>.</p>
331
      </attribute>
332
333
    </attributes>
334
    
335
    <h3>Using file-based Authentication and Authorisation</h3>
336
337
    <p>If this listener was configured in server.xml as:
338
  <source>
339
  &lt;Listener className="org.apache.catalina.mbeans.JmxRemoteLifecycleListener"
340
          rmiRegistryPortPlatform="10001" rmiServerPortPlatform="10002" /&gt;
341
  </source>
342
    with the following system properties set (e.g. in setenv.sh):
343
  <source>
344
  -Dcom.sun.management.jmxremote.password.file=$CATALINA_BASE/conf/jmxremote.password
345
  -Dcom.sun.management.jmxremote.access.file=$CATALINA_BASE/conf/jmxremote.access
346
  -Dcom.sun.management.jmxremote.ssl=false
347
  </source>
348
    $CATALINA_BASE/conf/jmxremote.password containing:
349
  <source>
350
  admin letmein
351
  </source>
352
    $CATALINA_BASE/conf/jmxremote.access containing:
353
  <source>
354
  admin readwrite
355
  </source>
356
    then opening ports 10001 (RMI Registry) and 10002 (JMX/RMI Server) in your
357
    firewall would enable jconsole to connect to a Tomcat instance running
358
    behind a firewall using a connection string of the form:
359
  <source>
360
  service:jmx:rmi://&lt;hostname&gt;:10002/jndi/rmi://&lt;hostname&gt;:10001/jmxrmi
361
  </source>
362
    with a user name of <code>admin</code> and a password of
363
    <code>letmein</code>.
364
    </p>
365
366
    <h3>Using JAAS</h3>
367
368
    <p>If we use the following system properties instead:
369
  <source>
370
  -Dcom.sun.management.jmxremote.login.config=Tomcat
371
  -Djava.security.auth.login.config=$CATALINA_BASE/conf/login.config
372
  -Dcom.sun.management.jmxremote.access.file=$CATALINA_BASE/conf/jmxremote.access
373
  -Dcom.sun.management.jmxremote.ssl=false
374
  </source>
375
    $CATALINA_BASE/conf/login.config containing your choice of JAAS LoginModule implementation, for example:
376
  <source>
377
  Tomcat { /* should match to the com.sun.management.jmxremote.login.config property */
378
379
    /* for illustration purposes only */
380
    com.sun.security.auth.module.LdapLoginModule REQUIRED
381
      userProvider="ldap://ldap-svr/ou=people,dc=example,dc=com"
382
      userFilter="(&amp;(uid={USERNAME})(objectClass=inetOrgPerson))"
383
      authzIdentity="admin"
384
      debug=true;
385
  };
386
  </source>
387
    $CATALINA_BASE/conf/jmxremote.access containing:
388
  <source>
389
  admin readwrite
390
  </source>
391
    then we would need to provide LDAP credentials instead.
392
    </p>
393
    
394
    <p><strong>Note that the examples above do not use SSL. JMX access should
395
    be considered equivalent to administrative access and secured accordingly.
396
    </strong></p>
397
398
  </subsection>
399
354
</section>
400
</section>
355
401
356
</body>
402
</body>

Return to bug 51182