funkman 2003/06/24 19:24:51
Modified: webapps/docs manager-howto.xml
Log:
add some docs about the JMXProxy servlet
Revision Changes Path
1.6 +100 -9 jakarta-tomcat-catalina/webapps/docs/manager-howto.xml
Index: manager-howto.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-catalina/webapps/docs/manager-howto.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- manager-howto.xml 12 May 2003 21:30:39 -0000 1.5
+++ manager-howto.xml 25 Jun 2003 02:24:51 -0000 1.6
@@ -38,6 +38,13 @@
</blockquote>
<a href="#Executing Manager Commands With Ant">
Executing Manager Commands With Ant</a><br />
+<a href="#Using the JMX Proxy Servlet">
+Using the JMX Proxy Servlet</a><br />
+<blockquote>
+<a href="#What is JMX Proxy Servlet">What is JMX Proxy Servlet?</a><br />
+<a href="#JMX Query command">Query command</a><br />
+<a href="#JMX Set command">Set command</a><br />
+</blockquote>
</p>
</section>
@@ -283,8 +290,8 @@
<ul>
<li><code>update</code>: When set to true, any existing update will be
undeployed first. The default value is set to false.</li>
-<li><code>tag</code>: Specifying a tag name, this allows associating the
- deployed webapp with a version number. The application version can
+<li><code>tag</code>: Specifying a tag name, this allows associating the
+ deployed webapp with a version number. The application version can
be later redeployed when needed using only the tag.</li>
<li><code>pause</code>: Pause webapps so that incoming connections are not lost
during an application update. This option is only used with the update
@@ -312,7 +319,7 @@
application using this context path, or choose a different context path
for the new one. The <code>update</code> parameter may be specified as
a parameter on the URL, with a value of <code>true</code> to avoid this
- error. In that case, an undeploy will be performed on an existing
+ error. In that case, an undeploy will be performed on an existing
application before performing the deployment.</p>
</blockquote></li>
<li><em>Encountered exception</em>
@@ -348,8 +355,8 @@
<h3>Install a version of a previously deployed webapp</h3>
<p>This can be used to deploy a previous version of a web applicaion, which
-has been deployed using the <code>tag</code> attribute. Note that the work
-directory for the manager webapp will contain the previously deployed WARs;
+has been deployed using the <code>tag</code> attribute. Note that the work
+directory for the manager webapp will contain the previously deployed WARs;
removing it would make the deployment fail.
<source>
http://localhost:8080/manager/deploy?path=/footoo&tag=footag
@@ -368,7 +375,7 @@
the entire WAR file.</p>
<p>In this example the web application located in the directory
-<code>/path/to/foo</code> on the Tomcat server is installed as the
+<code>/path/to/foo</code> on the Tomcat server is installed as the
web application context named <code>/footoo</code>.
<source>
http://localhost:8080/manager/deploy?path=/footoo&war=file:/path/to/foo
@@ -488,7 +495,7 @@
application using this context path, or choose a different context path
for the new one. The <code>update</code> parameter may be specified as
a parameter on the URL, with a value of <code>true</code> to avoid this
- error. In that case, an undeploy will be performed on an existing
+ error. In that case, an undeploy will be performed on an existing
application before performing the deployment.</p>
</blockquote></li>
<li><em>Document base does not exist or is not a readable directory</em>
@@ -858,8 +865,8 @@
<p><strong><font color="red">WARNING</font> - This command will
delete the contents of the web application directory if it exists within the
<code>appBase</code> directory (typically "webapps") for this virtual host
-</strong>. This will also delete the source .WAR if expanding occurred, as
-well as the XML Context definition. If you simply want to take an application
+</strong>. This will also delete the source .WAR if expanding occurred, as
+well as the XML Context definition. If you simply want to take an application
out of service, you should use the <code>/stop</code> command instead.</p>
<p>Signal an existing application to gracefully shut itself down, and
@@ -993,6 +1000,90 @@
</pre>
</section>
+
+<section name="Using the JMX Proxy Servlet">
+
+ <subsection name="What is JMX Proxy Servlet">
+ The JMX Proxy Servlet is a lightweight proxy to get and set the
+ tomcat internals. (Or any class that has been exposed via an MBean)
+ Its usage is not very user friendly but the UI is
+ extremely help for integrating command line scripts for monitoring
+ and changing the internals of tomcat. You can do two things with the proxy:
+ get information and set information. For you to really understand the
+ JMX Proxy Servlet, you should have a general understanding of JMX.
+ If you don't know what JMX is, then prepare to be confused.
+ </subsection>
+
+ <subsection name="JMX Query command">
+ This takes the form:
+ <source>
+http://webserver/manager/jmxproxy/?qry=STUFF
+ </source>
+ Where <code>STUFF</code> is the JMX query you wish to perform. For example,
+ here are some queries you might wish to run:
+ <ul>
+ <li>
+ <code>qry=*%3Atype%3DRequestProcessor%2C* -->
+ type=RequestProcessor</code> which will locate all
+ workers which can process requests and report
+ their state.
+ </li>
+ <li>
+ <code>qry=*%3Aj2eeType=Servlet%2c* -->
+ j2eeType=Servlet</code> which return all loaded servlets.
+ </li>
+ <li>
+
<code>qry=Catalina%3Atype%3DEnvironment%2Cresourcetype%3DGlobal%2Cname%3DsimpleValue
-->
+ Catalina:type=Environment,resourcetype=Global,name=simpleValue</code>
+ which look for a specific MBean by the given name.
+ </li>
+ </ul>
+ You'll need to experiment with this to really understand its capabilites.
+ If you provide no <code>qry</code> parameter, then all of the MBeans will
+ be displayed. We really recommend looking at the tomcat source code and
+ understand the JMX spec to get a better understanding of all the queries
+ you may run.
+ </subsection>
+
+ <subsection name="JMX Set command">
+ Now that you can query an MBean, its time to muck with Tomcat's internals!
+ The general form of the set command is :
+ <source>
+http://webserver/manager/jmxproxy/?set=BEANNAME&att=MYATTRIBUTE&val=NEWVALUE
+ </source>
+ So you need to provide 3 request parameters:
+ <ol>
+ <li><code>set</code>: The full bean name</li>
+ <li><code>att</code>: The attribute you wish to alter</li>
+ <li><code>val</code>: The new value </li>
+ </ol>
+ If all goes ok, then it will say OK, otherwise an error message will be
+ shown. For example, lets say we wish to turn up debugging on the fly for the
+ <code>ErrorReportValve</code>. The following will set debugging to 10.
+ <source>
+http://localhost:8080/manager/jmxproxy/
+?set=Catalina%3Atype%3DValve%2Cname%3DErrorReportValve%2Chost%3Dlocalhost&att=debug&val=10
+ </source>
+ and my result is (YMMV):
+ <source>
+Result: ok
+ </source>
+
+ Here is what I see if I pass in a bad value. Here is the URL I used,
+ I try set debugging equal to 'cowbell':
+ <source>
+http://localhost:8080/manager/jmxproxy/
+?set=Catalina%3Atype%3DValve%2Cname%3DErrorReportValve%2Chost%3Dlocalhost&att=debug&val=cowbell
+ </source>
+ When I try that, my result is
+ <source>
+Error: java.lang.NumberFormatException: For input string: "cowbell"
+ </source>
+ </subsection>
+
+
+</section>
+
</body>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
