You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by ma...@apache.org on 2013/08/29 11:02:41 UTC
svn commit: r1518540 [3/3] - in /tomcat/trunk: modules/jdbc-pool/doc/
webapps/docs/
Modified: tomcat/trunk/webapps/docs/manager-howto.xml
URL: http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/manager-howto.xml?rev=1518540&r1=1518539&r2=1518540&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/manager-howto.xml (original)
+++ tomcat/trunk/webapps/docs/manager-howto.xml Thu Aug 29 09:02:41 2013
@@ -70,13 +70,11 @@ Manager web application <code>Context</c
<code>manager.xml</code> context configuration file in the
<code>$CATALINA_BASE/conf/[enginename]/[hostname]</code> folder. Here is an
example:</p>
-<pre>
-<Context privileged="true" antiResourceLocking="false"
- docBase="${catalina.home}/webapps/manager">
- <Valve className="org.apache.catalina.valves.RemoteAddrValve"
- allow="127\.0\.0\.1" />
-</Context>
-</pre>
+<source><![CDATA[<Context privileged="true" antiResourceLocking="false"
+ docBase="${catalina.home}/webapps/manager">
+ <Valve className="org.apache.catalina.valves.RemoteAddrValve"
+ allow="127\.0\.0\.1" />
+</Context>]]></source>
<p>If you have Tomcat configured to support multiple virtual hosts
(websites) you would need to configure a Manager for each.</p>
@@ -89,11 +87,11 @@ your website host name: <code>http://lo
<li>A minimal version using HTTP requests only which is suitable for use
by scripts setup by system administrators. Commands are given as part of the
request URI, and responses are in the form of simple text that can be easily
-parsed and processed. See <a href="#Supported Manager Commands">
+parsed and processed. See <a href="#Supported_Manager_Commands">
Supported Manager Commands</a> for more information.</li>
<li>A convenient set of task definitions for the <em>Ant</em>
(version 1.4 or later) build tool. See
-<a href="#Executing Manager Commands With Ant">Executing Manager Commands
+<a href="#Executing_Manager_Commands_With_Ant">Executing Manager Commands
With Ant</a> for more information.</li>
</ul>
@@ -101,13 +99,13 @@ With Ant</a> for more information.</li>
<section name="Configuring Manager Application Access">
- <blockquote>
+
<p><em>The description below uses the variable name $CATALINA_BASE to refer the
base directory against which most relative paths are resolved. If you have
not configured Tomcat for multiple instances by setting a CATALINA_BASE
directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
the directory into which you have installed Tomcat.</em></p>
- </blockquote>
+
<p>It would be quite unsafe to ship Tomcat with default settings that allowed
anyone on the Internet to execute the Manager application on your server.
@@ -175,9 +173,7 @@ Exactly how the usernames/passwords are
edited with any text editor. This file contains an XML
<code><user></code> for each individual user, which might
look something like this:
-<source>
-<user name="craigmcc" password="secret" roles="standard,manager-script" />
-</source>
+<source><![CDATA[<user name="craigmcc" password="secret" roles="standard,manager-script" />]]></source>
which defines the username and password used by this individual to
log on, and the role names he or she is associated with. You can
add the <strong>manager-script</strong> role to the comma-delimited
@@ -207,12 +203,10 @@ a <code>RemoteAddrValve</code> or <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>
-<pre>
-<Context privileged="true">
- <Valve className="org.apache.catalina.valves.RemoteAddrValve"
- allow="127\.0\.0\.1"/>
-</Context>
-</pre>
+<source><![CDATA[<Context privileged="true">
+ <Valve className="org.apache.catalina.valves.RemoteAddrValve"
+ allow="127\.0\.0\.1"/>
+</Context>]]></source>
</section>
@@ -221,9 +215,7 @@ an example of restricting access to the
<p>All commands that the Manager application knows how to process are
specified in a single request URI like this:</p>
-<source>
-http://{host}:{port}/manager/text/{command}?{parameters}
-</source>
+<source>http://{host}:{port}/manager/text/{command}?{parameters}</source>
<p>where <code>{host}</code> and <code>{port}</code> represent the hostname
and port number on which Tomcat is running, <code>{command}</code>
represents the Manager command you wish to execute, and
@@ -282,9 +274,7 @@ version of the messages.</p>
<subsection name="Deploy A New Application Remotely">
-<source>
-http://localhost:8080/manager/text/deploy?path=/foo
-</source>
+<source>http://localhost:8080/manager/text/deploy?path=/foo</source>
<p>Upload the web application archive (WAR) file that is specified as the
request data in this HTTP PUT request, install it into the <code>appBase</code>
@@ -311,15 +301,12 @@ opposite of the <code>/undeploy</code> c
<p>If installation and startup is successful, you will receive a response
like this:</p>
-<source>
-OK - Deployed application at context path /foo
-</source>
+<source>OK - Deployed application at context path /foo</source>
<p>Otherwise, the response will start with <code>FAIL</code> and include an
error message. Possible causes for problems include:</p>
<ul>
<li><em>Application already exists at path /foo</em>
- <blockquote>
<p>The context paths for all currently running web applications must be
unique. Therefore, you must undeploy the existing web
application using this context path, or choose a different context path
@@ -327,15 +314,14 @@ error message. Possible causes for prob
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
application before performing the deployment.</p>
- </blockquote></li>
+ </li>
<li><em>Encountered exception</em>
- <blockquote>
<p>An exception was encountered trying to start the new web application.
Check the Tomcat logs for the details, but likely explanations include
problems parsing your <code>/WEB-INF/web.xml</code> file, or missing
classes encountered when initializing application event listeners and
filters.</p>
- </blockquote></li>
+ </li>
</ul>
</subsection>
@@ -348,18 +334,16 @@ This command is the logical opposite of
<p>There are a number of different ways the deploy command can be used.</p>
-<h3>Deploy a previously deployed webapp</h3>
+<h5>Deploy a previously deployed webapp</h5>
<p>This can be used to deploy a previously deployed web application, 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;
removing it would make the deployment fail.</p>
-<source>
-http://localhost:8080/manager/text/deploy?path=/footoo&tag=footag
-</source>
+<source>http://localhost:8080/manager/text/deploy?path=/footoo&tag=footag</source>
-<h3>Deploy a Directory or WAR by URL</h3>
+<h5>Deploy a Directory or WAR by URL</h5>
<p>Deploy a web application directory or ".war" file located on the Tomcat
server. If no <code>path</code> is specified, the directory name or the war file
@@ -373,9 +357,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 deployed as the
web application context named <code>/footoo</code>.</p>
-<source>
-http://localhost:8080/manager/text/deploy?path=/footoo&war=file:/path/to/foo
-</source>
+<source>http://localhost:8080/manager/text/deploy?path=/footoo&war=file:/path/to/foo</source>
<p>In this example the ".war" file <code>/path/to/bar.war</code> on the
@@ -383,12 +365,10 @@ Tomcat server is deployed as the web app
<code>/bar</code>. Notice that there is no <code>path</code> parameter
so the context path defaults to the name of the web application archive
file without the ".war" extension.</p>
-<source>
-http://localhost:8080/manager/text/deploy?war=jar:file:/path/to/bar.war!/
-</source>
+<source>http://localhost:8080/manager/text/deploy?war=jar:file:/path/to/bar.war!/</source>
-<h3>Deploy a Directory or War from the Host appBase</h3>
+<h5>Deploy a Directory or War from the Host appBase</h5>
<p>Deploy a web application directory or ".war" file located in your Host
appBase directory. The directory name or the war file name without the ".war"
@@ -398,20 +378,16 @@ extension is used as the path.</p>
<code>foo</code> in the Host appBase directory of the Tomcat server is
deployed as the web application context named <code>/foo</code>. Notice
that the context path used is the name of the web application directory.</p>
-<source>
-http://localhost:8080/manager/text/deploy?war=foo
-</source>
+<source>http://localhost:8080/manager/text/deploy?war=foo</source>
<p>In this example the ".war" file <code>bar.war</code> located in your
Host appBase directory on the Tomcat server is deployed as the web
application context named <code>/bar</code>.</p>
-<source>
-http://localhost:8080/manager/text/deploy?war=bar.war
-</source>
+<source>http://localhost:8080/manager/text/deploy?war=bar.war</source>
-<h3>Deploy using a Context configuration ".xml" file</h3>
+<h5>Deploy using a Context configuration ".xml" file</h5>
<p>If the Host deployXML flag is set to true you can deploy a web
application using a Context configuration ".xml" file and an optional
@@ -423,10 +399,8 @@ configuration file.</p>
web application Context just as if it were configured in your
Tomcat <code>server.xml</code> configuration file. Here is an
example:</p>
-<source>
-<Context path="/foobar" docBase="/path/to/application/foobar">
-</Context>
-</source>
+<source><![CDATA[<Context path="/foobar" docBase="/path/to/application/foobar">
+</Context>]]></source>
<p>When the optional <code>war</code> parameter is set to the URL
@@ -435,21 +409,17 @@ docBase configured in the context config
<p>Here is an example of deploying an application using a Context
configuration ".xml" file.</p>
-<source>
-http://localhost:8080/manager/text/deploy?config=file:/path/context.xml
-</source>
+<source>http://localhost:8080/manager/text/deploy?config=file:/path/context.xml</source>
<p>Here is an example of deploying an application using a Context
configuration ".xml" file and a web application ".war" file located
on the server.</p>
-<source>
-http://localhost:8080/manager/text/deploy
- ?config=file:/path/context.xml&war=jar:file:/path/bar.war!/
-</source>
+<source>http://localhost:8080/manager/text/deploy
+ ?config=file:/path/context.xml&war=jar:file:/path/bar.war!/</source>
-<h3>Deployment Notes</h3>
+<h5>Deployment Notes</h5>
<p>If the Host is configured with unpackWARs=true and you deploy a war
file, the war will be unpacked into a directory in your Host appBase
@@ -467,19 +437,16 @@ also prevents them from deploying applic
files located outside of their Host appBase.</p>
-<h3>Deploy Response</h3>
+<h5>Deploy Response</h5>
<p>If installation and startup is successful, you will receive a response
like this:</p>
-<source>
-OK - Deployed application at context path /foo
-</source>
+<source>OK - Deployed application at context path /foo</source>
<p>Otherwise, the response will start with <code>FAIL</code> and include an
error message. Possible causes for problems include:</p>
<ul>
<li><em>Application already exists at path /foo</em>
- <blockquote>
<p>The context paths for all currently running web applications must be
unique. Therefore, you must undeploy the existing web
application using this context path, or choose a different context path
@@ -487,77 +454,66 @@ error message. Possible causes for prob
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
application before performing the deployment.</p>
- </blockquote></li>
+ </li>
<li><em>Document base does not exist or is not a readable directory</em>
- <blockquote>
<p>The URL specified by the <code>war</code> parameter must identify a
directory on this server that contains the "unpacked" version of a
web application, or the absolute URL of a web application archive (WAR)
file that contains this application. Correct the value specified by
the <code>war</code> parameter.</p>
- </blockquote></li>
+ </li>
<li><em>Encountered exception</em>
- <blockquote>
<p>An exception was encountered trying to start the new web application.
Check the Tomcat logs for the details, but likely explanations include
problems parsing your <code>/WEB-INF/web.xml</code> file, or missing
classes encountered when initializing application event listeners and
filters.</p>
- </blockquote></li>
+ </li>
<li><em>Invalid application URL was specified</em>
- <blockquote>
<p>The URL for the directory or web application that you specified
was not valid. Such URLs must start with <code>file:</code>, and URLs
for a WAR file must end in ".war".</p>
- </blockquote></li>
+ </li>
<li><em>Invalid context path was specified</em>
- <blockquote>
<p>The context path must start with a slash character. To reference the
ROOT web application use "/".</p>
- </blockquote></li>
+ </li>
<li><em>Context path must match the directory or WAR file name:</em>
- <blockquote>
- If the application war or directory is installed in your Host appBase
+ <p>If the application war or directory is installed in your Host appBase
directory and either the Host is configured with autoDeploy=true the
Context path must match the directory name or war file name without
- the ".war" extension.
- </blockquote></li>
+ the ".war" extension.</p>
+ </li>
<li><em>Only web applications in the Host web application directory can
be installed</em>
- <blockquote>
+ <p>
If the Host deployXML flag is set to false this error will happen
if an attempt is made to deploy a web application directory or
".war" file outside of the Host appBase directory.
- </blockquote></li>
+ </p></li>
</ul>
</subsection>
<subsection name="List Currently Deployed Applications">
-<source>
-http://localhost:8080/manager/text/list
-</source>
+<source>http://localhost:8080/manager/text/list</source>
<p>List the context paths, current status (<code>running</code> or
<code>stopped</code>), and number of active sessions for all currently
deployed web applications. A typical response immediately
after starting Tomcat might look like this:</p>
-<source>
-OK - Listed applications for virtual host localhost
+<source>OK - Listed applications for virtual host localhost
/webdav:running:0
/examples:running:0
/manager:running:0
-/:running:0
-</source>
+/:running:0</source>
</subsection>
<subsection name="Reload An Existing Application">
-<source>
-http://localhost:8080/manager/text/reload?path=/examples
-</source>
+<source>http://localhost:8080/manager/text/reload?path=/examples</source>
<p>Signal an existing application to shut itself down and reload. This can
be useful when the web application context is not reloadable and you have
@@ -572,34 +528,29 @@ then start the web application.
</p>
<p>If this command succeeds, you will see a response like this:</p>
-<source>
-OK - Reloaded application at context path /examples
-</source>
+<source>OK - Reloaded application at context path /examples</source>
<p>Otherwise, the response will start with <code>FAIL</code> and include an
error message. Possible causes for problems include:</p>
<ul>
<li><em>Encountered exception</em>
- <blockquote>
<p>An exception was encountered trying to restart the web application.
Check the Tomcat logs for the details.</p>
- </blockquote></li>
+ </li>
<li><em>Invalid context path was specified</em>
- <blockquote>
<p>The context path must start with a slash character. To reference the
ROOT web application use "/".</p>
- </blockquote></li>
+ </li>
<li><em>No context exists for path /foo</em>
- <blockquote>
<p>There is no deployed application on the context path
that you specified.</p>
- </blockquote></li>
+ </li>
<li><em>No context path was specified</em>
- <blockquote>
+ <p>
The <code>path</code> parameter is required.
- </blockquote></li>
+ </p></li>
<li><em>Reload not supported on WAR deployed at path /foo</em>
- <blockquote>
+ <p>
Currently, application reloading (to pick up changes to the classes or
<code>web.xml</code> file) is not supported when a web application is
deployed directly from a WAR file. It only works when the web application
@@ -607,16 +558,14 @@ error message. Possible causes for prob
you should <code>undeploy</code> and then <code>deploy</code> or
<code>deploy</code> with the <code>update</code> parameter the
application again to pick up your changes.
- </blockquote></li>
+ </p></li>
</ul>
</subsection>
<subsection name="List OS and JVM Properties">
-<source>
-http://localhost:8080/manager/text/serverinfo
-</source>
+<source>http://localhost:8080/manager/text/serverinfo</source>
<p>Lists information about the Tomcat version, OS, and JVM properties.</p>
@@ -624,19 +573,16 @@ http://localhost:8080/manager/text/serve
include an error message. Possible causes for problems include:</p>
<ul>
<li><em>Encountered exception</em>
- <blockquote>
<p>An exception was encountered trying to enumerate the system properties.
Check the Tomcat logs for the details.</p>
- </blockquote></li>
+ </li>
</ul>
</subsection>
<subsection name="List Available Global JNDI Resources">
-<source>
-http://localhost:8080/manager/text/resources[?type=xxxxx]
-</source>
+<source>http://localhost:8080/manager/text/resources[?type=xxxxx]</source>
<p>List the global JNDI resources that are available for use in resource
links for context configuration files. If you specify the <code>type</code>
@@ -648,13 +594,9 @@ parameter, resources of all types will b
<p>Depending on whether the <code>type</code> request parameter is specified
or not, the first line of a normal response will be:</p>
-<pre>
- OK - Listed global resources of all types
-</pre>
+<source>OK - Listed global resources of all types</source>
<p>or</p>
-<pre>
- OK - Listed global resources of type xxxxx
-</pre>
+<source>OK - Listed global resources of type xxxxx</source>
<p>followed by one line for each resource. Each line is composed of fields
delimited by colon characters (":"), as follows:</p>
<ul>
@@ -669,15 +611,13 @@ delimited by colon characters (":"), as
include an error message. Possible causes for problems include:</p>
<ul>
<li><em>Encountered exception</em>
- <blockquote>
<p>An exception was encountered trying to enumerate the global JNDI
resources. Check the Tomcat logs for the details.</p>
- </blockquote></li>
+ </li>
<li><em>No global JNDI resources are available</em>
- <blockquote>
<p>The Tomcat server you are running has been configured without
global JNDI resources.</p>
- </blockquote></li>
+ </li>
</ul>
@@ -685,29 +625,23 @@ include an error message. Possible caus
<subsection name="Session Statistics">
-<source>
-http://localhost:8080/manager/text/sessions?path=/examples
-</source>
+<source>http://localhost:8080/manager/text/sessions?path=/examples</source>
<p>Display the default session timeout for a web application, and the
number of currently active sessions that fall within ten-minute ranges of
their actual timeout times. For example, after restarting Tomcat and then
executing one of the JSP samples in the <code>/examples</code> web app,
you might get something like this:</p>
-<source>
-OK - Session information for application at context path /examples
+<source>OK - Session information for application at context path /examples
Default maximum session inactive interval 30 minutes
-30 - <40 minutes:1 sessions
-</source>
+30 - <40 minutes:1 sessions</source>
</subsection>
<subsection name="Start an Existing Application">
-<source>
-http://localhost:8080/manager/text/start?path=/examples
-</source>
+<source>http://localhost:8080/manager/text/start?path=/examples</source>
<p>Signal a stopped application to restart, and make itself available again.
Stopping and starting is useful, for example, if the database required by
@@ -716,41 +650,34 @@ stop the web application that relies on
users continuously encounter database exceptions.</p>
<p>If this command succeeds, you will see a response like this:</p>
-<source>
-OK - Started application at context path /examples
-</source>
+<source>OK - Started application at context path /examples</source>
<p>Otherwise, the response will start with <code>FAIL</code> and include an
error message. Possible causes for problems include:</p>
<ul>
<li><em>Encountered exception</em>
- <blockquote>
<p>An exception was encountered trying to start the web application.
Check the Tomcat logs for the details.</p>
- </blockquote></li>
+ </li>
<li><em>Invalid context path was specified</em>
- <blockquote>
<p>The context path must start with a slash character. To reference the
ROOT web application use "/".</p>
- </blockquote></li>
+ </li>
<li><em>No context exists for path /foo</em>
- <blockquote>
<p>There is no deployed application on the context path
that you specified.</p>
- </blockquote></li>
+ </li>
<li><em>No context path was specified</em>
- <blockquote>
+ <p>
The <code>path</code> parameter is required.
- </blockquote></li>
+ </p></li>
</ul>
</subsection>
<subsection name="Stop an Existing Application">
-<source>
-http://localhost:8080/manager/text/stop?path=/examples
-</source>
+<source>http://localhost:8080/manager/text/stop?path=/examples</source>
<p>Signal an existing application to make itself unavailable, but leave it
deployed. Any request that comes in while an application is
@@ -758,32 +685,26 @@ stopped will see an HTTP error 404, and
"stopped" on a list applications command.</p>
<p>If this command succeeds, you will see a response like this:</p>
-<source>
-OK - Stopped application at context path /examples
-</source>
+<source>OK - Stopped application at context path /examples</source>
<p>Otherwise, the response will start with <code>FAIL</code> and include an
error message. Possible causes for problems include:</p>
<ul>
<li><em>Encountered exception</em>
- <blockquote>
<p>An exception was encountered trying to stop the web application.
Check the Tomcat logs for the details.</p>
- </blockquote></li>
+ </li>
<li><em>Invalid context path was specified</em>
- <blockquote>
<p>The context path must start with a slash character. To reference the
ROOT web application use "/".</p>
- </blockquote></li>
+ </li>
<li><em>No context exists for path /foo</em>
- <blockquote>
<p>There is no deployed application on the context path
that you specified.</p>
- </blockquote></li>
+ </li>
<li><em>No context path was specified</em>
- <blockquote>
The <code>path</code> parameter is required.
- </blockquote></li>
+ </li>
</ul>
</subsection>
@@ -791,11 +712,9 @@ error message. Possible causes for prob
<subsection name="Undeploy an Existing Application">
-<source>
-http://localhost:8080/manager/text/undeploy?path=/examples
-</source>
+<source>http://localhost:8080/manager/text/undeploy?path=/examples</source>
-<p><strong><font color="red">WARNING</font> - This command will delete any web
+<p><strong><span style="color: red;">WARNING</span> - This command will delete any web
application artifacts that exist within <code>appBase</code> directory
(typically "webapps") for this virtual host</strong>.
This will delete the the application .WAR, if present,
@@ -813,41 +732,33 @@ this virtual host. This command is the
<code>/deploy</code> command.</p>
<p>If this command succeeds, you will see a response like this:</p>
-<source>
-OK - Undeployed application at context path /examples
-</source>
+<source>OK - Undeployed application at context path /examples</source>
<p>Otherwise, the response will start with <code>FAIL</code> and include an
error message. Possible causes for problems include:</p>
<ul>
<li><em>Encountered exception</em>
- <blockquote>
<p>An exception was encountered trying to undeploy the web application.
Check the Tomcat logs for the details.</p>
- </blockquote></li>
+ </li>
<li><em>Invalid context path was specified</em>
- <blockquote>
<p>The context path must start with a slash character. To reference the
ROOT web application use "/".</p>
- </blockquote></li>
+ </li>
<li><em>No context exists for path /foo</em>
- <blockquote>
<p>There is no deployed application on the context path
that you specified.</p>
- </blockquote></li>
+ </li>
<li><em>No context path was specified</em>
- <blockquote>
The <code>path</code> parameter is required.
- </blockquote></li>
+ </li>
</ul>
</subsection>
<subsection name="Finding memory leaks">
-<source>
-http://localhost:8080/manager/text/findleaks[?statusLine=[true|false]]
-</source>
+<source>http://localhost:8080/manager/text/findleaks[?statusLine=[true|false]]</source>
<p><strong>The find leaks diagnostic triggers a full garbage collection. It
should be used with extreme caution on production systems.</strong></p>
@@ -866,9 +777,7 @@ If you want to make sure, that the diagn
GC, you will need to check using tools like GC logging, JConsole or similar.</p>
<p>If this command succeeds, you will see a response like this:</p>
-<source>
-/leaking-webapp
-</source>
+<source>/leaking-webapp</source>
<p>If you wish to see a status line included in the response then include the
<code>statusLine</code> query parameter in the request with a value of
@@ -886,17 +795,14 @@ has been reloaded several times, it may
<subsection name="Connector SSL diagnostics">
-<source>
-http://localhost:8080/manager/text/sslConnectorCiphers
-</source>
+<source>http://localhost:8080/manager/text/sslConnectorCiphers</source>
<p>The SSL Connector/Ciphers diagnostic lists the SSL ciphers that are currently
configured for each connector. For BIO and NIO, the names of the individual
cipher suites are listed. For APR, the value of SSLCipherSuite is returned.</p>
<p>The response will ook something like this:</p>
-<source>
-OK - Connector / SSL Cipher information
+<source>OK - Connector / SSL Cipher information
Connector[HTTP/1.1-8080]
SSL is not enabled for this connector
Connector[HTTP/1.1-8443]
@@ -904,8 +810,7 @@ Connector[HTTP/1.1-8443]
TLS_DHE_RSA_WITH_AES_128_CBC_SHA
TLS_ECDH_RSA_WITH_AES_128_CBC_SHA
TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA
- ...
-</source>
+ ...</source>
</subsection>
@@ -982,57 +887,53 @@ commands, you must perform the following
<code><taskdef></code> element. Therefore, your <code>build.xml</code>
file might look something like this:</p>
-<table border="1">
-<tr><td><pre>
-<project name="My Application" default="compile" basedir=".">
-
- <!-- Configure the directory into which the web application is built -->
- <property name="build" value="${basedir}/build"/>
-
- <!-- Configure the context path for this application -->
- <property name="path" value="/myapp"/>
-
- <!-- Configure properties to access the Manager application -->
- <property name="url" value="http://localhost:8080/manager/text"/>
- <property name="username" value="myusername"/>
- <property name="password" value="mypassword"/>
-
- <!-- Configure the custom Ant tasks for the Manager application -->
- <taskdef name="deploy" classname="org.apache.catalina.ant.DeployTask"/>
- <taskdef name="list" classname="org.apache.catalina.ant.ListTask"/>
- <taskdef name="reload" classname="org.apache.catalina.ant.ReloadTask"/>
- <taskdef name="findleaks" classname="org.apache.catalina.ant.FindLeaksTask"/>
- <taskdef name="resources" classname="org.apache.catalina.ant.ResourcesTask"/>
- <taskdef name="start" classname="org.apache.catalina.ant.StartTask"/>
- <taskdef name="stop" classname="org.apache.catalina.ant.StopTask"/>
- <taskdef name="undeploy" classname="org.apache.catalina.ant.UndeployTask"/>
-
- <!-- Executable Targets -->
- <target name="compile" description="Compile web application">
- <!-- ... construct web application in ${build} subdirectory, and
- generated a ${path}.war ... -->
- </target>
-
- <target name="deploy" description="Install web application"
- depends="compile">
- <deploy url="${url}" username="${username}" password="${password}"
- path="${path}" war="file:${build}${path}.war"/>
- </target>
-
- <target name="reload" description="Reload web application"
- depends="compile">
- <reload url="${url}" username="${username}" password="${password}"
- path="${path}"/>
- </target>
-
- <target name="undeploy" description="Remove web application">
- <undeploy url="${url}" username="${username}" password="${password}"
- path="${path}"/>
- </target>
+<source><![CDATA[<project name="My Application" default="compile" basedir=".">
-</project>
-</pre></td></tr>
-</table>
+ <!-- Configure the directory into which the web application is built -->
+ <property name="build" value="${basedir}/build"/>
+
+ <!-- Configure the context path for this application -->
+ <property name="path" value="/myapp"/>
+
+ <!-- Configure properties to access the Manager application -->
+ <property name="url" value="http://localhost:8080/manager/text"/>
+ <property name="username" value="myusername"/>
+ <property name="password" value="mypassword"/>
+
+ <!-- Configure the custom Ant tasks for the Manager application -->
+ <taskdef name="deploy" classname="org.apache.catalina.ant.DeployTask"/>
+ <taskdef name="list" classname="org.apache.catalina.ant.ListTask"/>
+ <taskdef name="reload" classname="org.apache.catalina.ant.ReloadTask"/>
+ <taskdef name="findleaks" classname="org.apache.catalina.ant.FindLeaksTask"/>
+ <taskdef name="resources" classname="org.apache.catalina.ant.ResourcesTask"/>
+ <taskdef name="start" classname="org.apache.catalina.ant.StartTask"/>
+ <taskdef name="stop" classname="org.apache.catalina.ant.StopTask"/>
+ <taskdef name="undeploy" classname="org.apache.catalina.ant.UndeployTask"/>
+
+ <!-- Executable Targets -->
+ <target name="compile" description="Compile web application">
+ <!-- ... construct web application in ${build} subdirectory, and
+ generated a ${path}.war ... -->
+ </target>
+
+ <target name="deploy" description="Install web application"
+ depends="compile">
+ <deploy url="${url}" username="${username}" password="${password}"
+ path="${path}" war="file:${build}${path}.war"/>
+ </target>
+
+ <target name="reload" description="Reload web application"
+ depends="compile">
+ <reload url="${url}" username="${username}" password="${password}"
+ path="${path}"/>
+ </target>
+
+ <target name="undeploy" description="Remove web application">
+ <undeploy url="${url}" username="${username}" password="${password}"
+ path="${path}"/>
+ </target>
+
+</project>]]></source>
<p>Note: The definition of the resources task above will override the resources
datatype added in Ant 1.7. If you wish to use the resources datatype you will
@@ -1047,9 +948,7 @@ you can override their values from the c
consider it a security risk to include the real manager password in your
<code>build.xml</code> file's source code. To avoid this, omit the password
property, and specify it from the command line:</p>
-<pre>
- ant -Dpassword=secret deploy
-</pre>
+<source>ant -Dpassword=secret deploy</source>
<subsection name="Tasks output capture">
@@ -1059,95 +958,91 @@ properties or external files. They suppo
<code><redirector></code> type attributes:
</p>
-<table border="1" cellpadding="2" cellspacing="0">
-<tbody>
+<table class="defaultTable">
<tr>
-<td valign="top"><b>Attribute</b></td>
-<td valign="top"><b>Description</b></td>
-<td align="center" valign="top"><b>Required</b></td>
+<th>Attribute</th>
+<th>Description</th>
+<th style="text-align: center;">Required</th>
</tr>
<tr>
-<td valign="top">output</td>
-<td valign="top">Name of a file to which to write the output. If
+<td>output</td>
+<td>Name of a file to which to write the output. If
the error stream is not also redirected to a file or property, it will
appear in this output.</td>
-<td align="center" valign="top">No</td>
+<td style="text-align: center;">No</td>
</tr>
<tr>
-<td valign="top">error</td>
-<td valign="top">The file to which the standard error of the
+<td>error</td>
+<td>The file to which the standard error of the
command should be redirected.</td>
-<td align="center" valign="top">No</td>
+<td style="text-align: center;">No</td>
</tr>
<tr>
-<td valign="top">logError</td>
-<td valign="top">This attribute is used when you wish to see
+<td>logError</td>
+<td>This attribute is used when you wish to see
error output in Ant's log and you are redirecting output to a
file/property. The error output will not be included in the output
file/property. If you redirect error with the <i>error</i> or <i>errorProperty</i>
attributes, this will have no effect.</td>
-<td align="center" valign="top">No</td>
+<td style="text-align: center;">No</td>
</tr>
<tr>
-<td valign="top">append</td>
-<td valign="top">Whether output and error files should be
+<td>append</td>
+<td>Whether output and error files should be
appended to or overwritten. Defaults to <code>false</code>.</td>
-<td align="center" valign="top">No</td>
+<td style="text-align: center;">No</td>
</tr>
<tr>
-<td valign="top">createemptyfiles</td>
-<td valign="top">Whether output and error files should be created
+<td>createemptyfiles</td>
+<td>Whether output and error files should be created
even when empty. Defaults to <code>true</code>.</td>
-<td align="center" valign="top">No</td>
+<td style="text-align: center;">No</td>
</tr>
<tr>
-<td valign="top">outputproperty</td>
-<td valign="top">The name of a property in which the output of
+<td>outputproperty</td>
+<td>The name of a property in which the output of
the command should be stored. Unless the error stream is redirected to
a separate file or stream, this property will include the error output.</td>
-<td align="center" valign="top">No</td>
+<td style="text-align: center;">No</td>
</tr>
<tr>
-<td valign="top">errorproperty</td>
-<td valign="top">The name of a property in which the standard
+<td>errorproperty</td>
+<td>The name of a property in which the standard
error of the command should be stored.</td>
-<td align="center" valign="top">No</td>
+<td style="text-align: center;">No</td>
</tr>
-</tbody>
</table>
<p>A couple of additional attributes can also be specified:
</p>
-<table border="1" cellpadding="2" cellspacing="0">
-<tbody>
+<table class="defaultTable">
<tr>
-<td valign="top"><b>Attribute</b></td>
-<td valign="top"><b>Description</b></td>
-<td align="center" valign="top"><b>Required</b></td>
+<th>Attribute</th>
+<th>Description</th>
+<th style="text-align: center;">Required</th>
</tr>
<tr>
-<td valign="top">alwaysLog</td>
-<td valign="top">This attribute is used when you wish to see the
+<td>alwaysLog</td>
+<td>This attribute is used when you wish to see the
output you are capturing, appearing also in the Ant's log. It must not be
used unless you are capturing task output.
Defaults to <code>false</code>.
<em>This attribute will be supported directly by <code><redirector></code>
in Ant 1.6.3</em></td>
-<td align="center" valign="top">No</td>
+<td style="text-align: center;">No</td>
</tr>
<tr>
-<td valign="top">failonerror</td>
-<td valign="top">This attribute is used when you wish to avoid that
+<td>failonerror</td>
+<td>This attribute is used when you wish to avoid that
any manager command processing error terminates the ant execution. Defaults to <code>true</code>.
It must be set to <code>false</code>, if you want to capture error output,
otherwise execution will terminate before anything can be captured.
-<br></br>
+<br/>
This attribute acts only on manager command execution,
any wrong or missing command attribute will still cause Ant execution termination.
</td>
-<td align="center" valign="top">No</td>
+<td style="text-align: center;">No</td>
</tr>
-</tbody>
</table>
<p>They also support the embedded <code><redirector></code> element
@@ -1164,73 +1059,69 @@ Here is a sample build file extract that
can be used:
</p>
-<table border="1">
-<tr><td><pre>
- <target name="manager.deploy"
+<source><![CDATA[ <target name="manager.deploy"
depends="context.status"
- if="context.notInstalled">
- <deploy url="${mgr.url}"
+ if="context.notInstalled">
+ <deploy url="${mgr.url}"
username="${mgr.username}"
password="${mgr.password}"
path="${mgr.context.path}"
- config="${mgr.context.descriptor}"/>
- </target>
+ config="${mgr.context.descriptor}"/>
+ </target>
- <target name="manager.deploy.war"
+ <target name="manager.deploy.war"
depends="context.status"
- if="context.deployable">
- <deploy url="${mgr.url}"
+ if="context.deployable">
+ <deploy url="${mgr.url}"
username="${mgr.username}"
password="${mgr.password}"
update="${mgr.update}"
path="${mgr.context.path}"
- war="${mgr.war.file}"/>
- </target>
+ war="${mgr.war.file}"/>
+ </target>
- <target name="context.status">
- <property name="running" value="${mgr.context.path}:running"/>
- <property name="stopped" value="${mgr.context.path}:stopped"/>
+ <target name="context.status">
+ <property name="running" value="${mgr.context.path}:running"/>
+ <property name="stopped" value="${mgr.context.path}:stopped"/>
- <list url="${mgr.url}"
+ <list url="${mgr.url}"
outputproperty="ctx.status"
username="${mgr.username}"
- password="${mgr.password}">
- </list>
+ password="${mgr.password}">
+ </list>
- <condition property="context.running">
- <contains string="${ctx.status}" substring="${running}"/>
- </condition>
- <condition property="context.stopped">
- <contains string="${ctx.status}" substring="${stopped}"/>
- </condition>
- <condition property="context.notInstalled">
- <and>
- <isfalse value="${context.running}"/>
- <isfalse value="${context.stopped}"/>
- </and>
- </condition>
- <condition property="context.deployable">
- <or>
- <istrue value="${context.notInstalled}"/>
- <and>
- <istrue value="${context.running}"/>
- <istrue value="${mgr.update}"/>
- </and>
- <and>
- <istrue value="${context.stopped}"/>
- <istrue value="${mgr.update}"/>
- </and>
- </or>
- </condition>
- <condition property="context.undeployable">
- <or>
- <istrue value="${context.running}"/>
- <istrue value="${context.stopped}"/>
- </or>
- </condition>
- </target>
-</pre></td></tr>
-</table>
+ <condition property="context.running">
+ <contains string="${ctx.status}" substring="${running}"/>
+ </condition>
+ <condition property="context.stopped">
+ <contains string="${ctx.status}" substring="${stopped}"/>
+ </condition>
+ <condition property="context.notInstalled">
+ <and>
+ <isfalse value="${context.running}"/>
+ <isfalse value="${context.stopped}"/>
+ </and>
+ </condition>
+ <condition property="context.deployable">
+ <or>
+ <istrue value="${context.notInstalled}"/>
+ <and>
+ <istrue value="${context.running}"/>
+ <istrue value="${mgr.update}"/>
+ </and>
+ <and>
+ <istrue value="${context.stopped}"/>
+ <istrue value="${mgr.update}"/>
+ </and>
+ </or>
+ </condition>
+ <condition property="context.undeployable">
+ <or>
+ <istrue value="${context.running}"/>
+ <istrue value="${context.stopped}"/>
+ </or>
+ </condition>
+ </target>]]></source>
<p><strong>WARNING:</strong> even if it doesn't make many sense, and is always a bad idea,
calling a Catalina task more than once,
@@ -1265,12 +1156,10 @@ see the output of each task call appende
</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:
+ <p>This takes the form:</p>
+<source>http://webserver/manager/jmxproxy/?qry=STUFF</source>
+ <p>Where <code>STUFF</code> is the JMX query you wish to perform. For example,
+ here are some queries you might wish to run:</p>
<ul>
<li>
<code>qry=*%3Atype%3DRequestProcessor%2C* -->
@@ -1288,96 +1177,85 @@ http://webserver/manager/jmxproxy/?qry=S
which look for a specific MBean by the given name.
</li>
</ul>
+ <p>
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.
+ </p>
</subsection>
<subsection name="JMX Get command">
+ <p>
The JXMProxyServlet also supports a "get" command that you can use to
fetch the value of a specific MBean's attribute. The general form of
the <code>get</code> command is:
+ </p>
-<source>
-http://webserver/manager/jmxproxy/?get=BEANNAME&att=MYATTRIBUTE&key=MYKEY
-</source>
+<source>http://webserver/manager/jmxproxy/?get=BEANNAME&att=MYATTRIBUTE&key=MYKEY</source>
- You must provide the following parameters:
+ <p>You must provide the following parameters:</p>
<ol>
<li><code>get</code>: The full bean name</li>
<li><code>att</code>: The attribute you wish to fetch</li>
<li><code>key</code>: (optional) The key into a CompositeData MBean attribute</li>
</ol>
-
+ <p>
If all goes well, then it will say OK, otherwise an error message will
be shown. For example, let's say we wish to fetch the current heap memory
data:
+ </p>
+
+<source>http://webserver/manager/jmxproxy/?get=java.lang:type=Memory&att=HeapMemoryUsage</source>
+
+ <p>Or, if you only want the "used" key:</p>
-<source>
-http://webserver/manager/jmxproxy/?get=java.lang:type=Memory&att=HeapMemoryUsage
-</source>
-
- Or, if you only want the "used" key:
-
-<source>
-http://webserver/manager/jmxproxy/
- ?get=java.lang:type=Memory&att=HeapMemoryUsage&key=used
-</source>
+<source>http://webserver/manager/jmxproxy/
+ ?get=java.lang:type=Memory&att=HeapMemoryUsage&key=used</source>
</subsection>
<subsection name="JMX Set command">
+ <p>
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:
+ </p>
+<source>http://webserver/manager/jmxproxy/?set=BEANNAME&att=MYATTRIBUTE&val=NEWVALUE</source>
+ <p>So you need to provide 3 request parameters:</p>
<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>
+ <p>
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/
+ </p>
+<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 'cow':
-<source>
-http://localhost:8080/manager/jmxproxy/
+ &att=debug&val=10</source>
+ <p>and my result is (YMMV):</p>
+<source>Result: ok</source>
+
+ <p>Here is what I see if I pass in a bad value. Here is the URL I used,
+ I try set debugging equal to 'cow':</p>
+<source>http://localhost:8080/manager/jmxproxy/
?set=Catalina%3Atype%3DValve%2Cname%3DErrorReportValve%2Chost%3Dlocalhost
- &att=debug&val=cow
-</source>
- When I try that, my result is
-<source>
-Error: java.lang.NumberFormatException: For input string: "cow"
-</source>
+ &att=debug&val=cow</source>
+ <p>When I try that, my result is</p>
+<source>Error: java.lang.NumberFormatException: For input string: "cow"</source>
</subsection>
<subsection name="JMX Invoke command">
<p>The <code>invoke</code> command enables methods to be called on MBeans. The
general form of the command is:</p>
-<source>
-http://webserver/manager/jmxproxy/
- ?invoke=BEANNAME&op=METHODNAME&ps=COMMASEPARATEDPARAMETERS
-</source>
+<source>http://webserver/manager/jmxproxy/
+ ?invoke=BEANNAME&op=METHODNAME&ps=COMMASEPARATEDPARAMETERS</source>
<p>For example, to call the <code>findConnectors()</code> method of the
<strong>Service</strong> use:</p>
-<source>
-http://localhost:8080/manager/jmxproxy/
- ?invoke=Catalina%3Atype%3DService&op=findConnectors&ps=
-</source>
+<source>http://localhost:8080/manager/jmxproxy/
+ ?invoke=Catalina%3Atype%3DService&op=findConnectors&ps=</source>
</subsection>
</section>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org