http://git-wip-us.apache.org/repos/asf/flex-blazeds/blob/5be16a28/attic/servers/apache-tomcat-6.0.29/webapps/docs/manager-howto.html ---------------------------------------------------------------------- diff --git a/attic/servers/apache-tomcat-6.0.29/webapps/docs/manager-howto.html b/attic/servers/apache-tomcat-6.0.29/webapps/docs/manager-howto.html new file mode 100644 index 0000000..ceedffb --- /dev/null +++ b/attic/servers/apache-tomcat-6.0.29/webapps/docs/manager-howto.html @@ -0,0 +1,1289 @@ +<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 6.0 - Manager App HOW-TO</title><meta content="Craig R. McClanahan" name="author"><style media="print" type="text/css"> + .noPrint {display: none;} + td#mainBody {width: 100%;} + </style></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/";><img border="0" alt=" + The Apache Tomcat Servlet/JSP Container + " align="right" src="./images/tomcat.gif"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 6.0</font></h1></td><td><!--APACHE LOGO--><a href="http://www.apache.org/";><img border="0" alt="Apache Logo" align="right" src="./images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><tr><!--LEFT SIDE NAVIGATION--><td class="noPrint" nowrap valign="top" width="20%"><p><strong>Links</strong></p><ul><li><a href="index.html">Docs Home</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ";>FAQ</a></li></ul><p><strong>User Guide</strong></p><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="appdev/index.html">3) First webapp</a></li><li><a href="deployer-howto.html">4) Deployer</a></li><li><a href="manager-howto.html">5) Manager</a></li><li><a href="realm-howto.html">6) Realms and AAA</a></li><li><a hr ef="security-manager-howto.html">7) Security Manager</a></li><li><a href="jndi-resources-howto.html">8) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">9) JDBC DataSources</a></li><li><a href="class-loader-howto.html">10) Classloading</a></li><li><a href="jasper-howto.html">11) JSPs</a></li><li><a href="ssl-howto.html">12) SSL</a></li><li><a href="ssi-howto.html">13) SSI</a></li><li><a href="cgi-howto.html">14) CGI</a></li><li><a href="proxy-howto.html">15) Proxy Support</a></li><li><a href="mbeans-descriptor-howto.html">16) MBean Descriptor</a></li><li><a href="default-servlet.html">17) Default Servlet</a></li><li><a href="cluster-howto.html">18) Clustering</a></li><li><a href="balancer-howto.html">19) Load Balancer</a></li><li><a href="connectors.html">20) Connectors</a></li><li><a href="monitoring.html">21) Monitoring and Management</a></li><li><a href="logging.html">22) Logging</a></li><li><a href="apr.html">23) APR/Native</a></li><li><a href="virtual-ho sting-howto.html">24) Virtual Hosting</a></li><li><a href="aio.html">25) Advanced IO</a></li><li><a href="extras.html">26) Additional Components</a></li><li><a href="maven-jars.html">27) Mavenized</a></li></ul><p><strong>Reference</strong></p><ul><li><a href="RELEASE-NOTES.txt">Release Notes</a></li><li><a href="config/index.html">Configuration</a></li><li><a href="api/index.html">Javadocs</a></li><li><a href="http://tomcat.apache.org/connectors-doc/";>JK 1.2 Documentation</a></li></ul><p><strong>Apache Tomcat Development</strong></p><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="http://wiki.apache.org/tomcat/TomcatVersions";>Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="funcspecs/index.html">Functional Specs.</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td id="mainBody" align="left" valign="top" width="80%"><h1>Apache Tomcat 6.0</h1> <h2>Manager App HOW-TO</h2><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote> +<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Configuring_Manager_Application_Access">Configuring Manager Application Access</a></li><li><a href="#Supported_Manager_Commands">Supported Manager Commands</a><ol><li><a href="#Deploy_A_New_Application_Remotely">Deploy A New Application Remotely</a></li><li><a href="#Deploy_A_New_Application_from_a_Local_Path">Deploy A New Application from a Local Path</a></li><li><a href="#List_Currently_Deployed_Applications">List Currently Deployed Applications</a></li><li><a href="#Reload_An_Existing_Application">Reload An Existing Application</a></li><li><a href="#List_OS_and_JVM_Properties">List OS and JVM Properties</a></li><li><a href="#List_Available_Global_JNDI_Resources">List Available Global JNDI Resources</a></li><li><a href="#List_Available_Security_Roles">List Available Security Roles</a></li><li><a href="#Session_Statistics">Session Statistics</a></li><li><a href="#Start_an_Existing_Application">Start an Existing Appl ication</a></li><li><a href="#Stop_an_Existing_Application">Stop an Existing Application</a></li><li><a href="#Undeploy_an_Existing_Application">Undeploy an Existing Application</a></li><li><a href="#Finding_memory_leaks">Finding memory leaks</a></li><li><a href="#Server_Status">Server Status</a></li></ol></li><li><a href="#Executing_Manager_Commands_With_Ant">Executing Manager Commands With Ant</a><ol><li><a href="#Tasks_output_capture">Tasks output capture</a></li></ol></li><li><a href="#Using_the_JMX_Proxy_Servlet">Using the JMX Proxy Servlet</a><ol><li><a href="#What_is_JMX_Proxy_Servlet">What is JMX Proxy Servlet</a></li><li><a href="#JMX_Query_command">JMX Query command</a></li><li><a href="#JMX_Set_command">JMX Set command</a></li></ol></li></ul> +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote> + +<p>In many production environments, it is very useful to have the capability +to deploy a new web application, or undeploy an existing one, without having +to shut down and restart the entire container. In addition, you can request +an existing application to reload itself, even if you have not declared it +to be <code>reloadable</code> in the Tomcat 6 server +configuration file.</p> + +<p>To support these capabilities, Tomcat 6 includes a web application +(installed by default on context path <code>/manager</code>) that supports +the following functions:</p> +<ul> +<li>Deploy a new web application from the uploaded contents of a WAR file.</li> +<li>Deploy a new web application, on a specified context path, from the + server file system.</li> +<li>List the currently deployed web applications, as well as the + sessions that are currently active for those web apps.</li> +<li>Reload an existing web application, to reflect changes in the + contents of <code>/WEB-INF/classes</code> or <code>/WEB-INF/lib</code>. + </li> +<li>List the OS and JVM property values.</li> +<li>List the available global JNDI resources, for use in deployment + tools that are preparing <code><ResourceLink></code> elements + nested in a <code><Context></code> deployment description.</li> +<li>List the available security roles defined in the user database.</li> +<li>Start a stopped application (thus making it available again).</li> +<li>Stop an existing application (so that it becomes unavailable), but + do not undeploy it.</li> +<li>Undeploy a deployed web application and delete its document base + directory (unless it was deployed from file system).</li> +</ul> + +<p>A default Tomcat installation includes the manager. To add an instance of the +Manager web application <code>Context</code> to a new host install the +<code>manager.xml</code> context configuration file in the +<code>$CATALINA_BASE/conf/[enginename]/[hostname]</code> folder. Here is an +example:</p> +<pre> +<Context path="/manager" debug="0" privileged="true" + docBase="/usr/local/kinetic/tomcat6/server/webapps/manager"> +</Context> +</pre> + +<p>If you have Tomcat configured to support multiple virtual hosts +(websites) you would need to configure a Manager for each.</p> + +<p>There are three ways to use the <code>Manager</code> web application.</p> +<ul> +<li>As an application with a user interface you use in your browser. +Here is an example URL where you can replace <code>localhost</code> with +your website host name: <code>http://localhost/manager/html/</code> .</li> +<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"> +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 +With Ant</a> for more information.</li> +</ul> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Configuring Manager Application Access"><!--()--></a><a name="Configuring_Manager_Application_Access"><strong>Configuring Manager Application Access</strong></a></font></td></tr><tr><td><blockquote> + + <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 6 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 6.</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. +Therefore, the Manager application is shipped with the requirement that anyone +who attempts to use it must authenticate themselves, using a username and +password that have the role <strong>manager</strong> associated with them. +Further, there is no username in the default users file +(<code>$CATALINA_BASE/conf/tomcat-users.xml</code>) that is assigned this +role. Therefore, access to the Manager application is completely disabled +by default.</p> + +<p>To enable access to the Manager web application, you must either create +a new username/password combination and associate the role name +<strong>manager</strong> with it, or add the <strong>manager</strong> role +to some existing username/password combination. Exactly where this is done +depends on which <code>Realm</code> implementation you are using:</p> +<ul> +<li><em>MemoryRealm</em> - If you have not customized your + <code>$CATALINA_BASE/conf/server.xml</code> to select a different one, + Tomcat 6 defaults to an XML-format file stored at + <code>$CATALINA_BASE/conf/tomcat-users.xml</code>, which can be + edited with any text editor. This file contains an XML + <code><user></code> for each individual user, which might + look something like this: +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +<user name="craigmcc" password="secret" roles="standard,manager" /> +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + 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</strong> role to the comma-delimited + <code>roles</code> attribute for one or more existing users, and/or + create new users with that assigned role.</li> +<li><em>JDBCRealm</em> - Your user and role information is stored in + a database accessed via JDBC. Add the <strong>manager</strong> role + to one or more existing users, and/or create one or more new users + with this role assigned, following the standard procedures for your + environment.</li> +<li><em>JNDIRealm</em> - Your user and role information is stored in + a directory server accessed via LDAP. Add the <strong>manager</strong> + role to one or more existing users, and/or create one or more new users + with this role assigned, following the standard procedures for your + environment.</li> +</ul> + +<p>The first time you attempt to issue one of the Manager commands +described in the next section, you will be challenged to log on using +BASIC authentication. The username and password you enter do not matter, +as long as they identify a valid user in the users database who possesses +the role <strong>manager</strong>.</p> + +<p>In addition to the password restrictions the manager web application +could be restricted by the remote IP address or host by adding a +<code>RemoteAddrValve</code> or <code>RemoteHostValve</code>. Here is +an example of restricting access to the localhost by IP address:</p> +<pre> +<Context path="/manager" privileged="true" + docBase="/usr/local/kinetic/tomcat6/server/webapps/manager"> + <Valve className="org.apache.catalina.valves.RemoteAddrValve" + allow="127\.0\.0\.1"/> +</Context> +</pre> +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Supported Manager Commands"><!--()--></a><a name="Supported_Manager_Commands"><strong>Supported Manager Commands</strong></a></font></td></tr><tr><td><blockquote> + +<p>All commands that the Manager application knows how to process are +specified in a single request URI like this:</p> +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +http://{host}:{port}/manager/{command}?{parameters} +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> +<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 +<code>{parameters}</code> represents the query parameters +that are specific to that command. In the illustrations below, customize +the host and port appropriately for your installation.</p> + +<p>Most commands accept one or more of the following query parameters:</p> +<ul> +<li><strong>path</strong> - The context path (including the leading slash) + of the web application you are dealing with. To select the ROOT web + application, specify "/". <strong>NOTE</strong> - + It is not possible to perform administrative commands on the + Manager application itself.</li> +<li><strong>war</strong> - URL of a web application archive (WAR) file, + pathname of a directory which contains the web application, or a + Context configuration ".xml" file. You can use URLs in any of the + following formats: + <ul> + <li><strong>file:/absolute/path/to/a/directory</strong> - The absolute + path of a directory that contains the unpacked version of a web + application. This directory will be attached to the context path + you specify without any changes.</li> + <li><strong>file:/absolute/path/to/a/webapp.war</strong> - The absolute + path of a web application archive (WAR) file. This is valid + <strong>only</strong> for the <code>/deploy</code> command, and is + the only acceptable format to that command.</li> + <li><strong>jar:file:/absolute/path/to/a/warfile.war!/</strong> - The + URL to a local web application archive (WAR) file. You can use any + syntax that is valid for the <code>JarURLConnection</code> class + for reference to an entire JAR file.</li> + <li><strong>file:/absolute/path/to/a/context.xml</strong> - The + absolute path of a web application Context configuration ".xml" + file which contains the Context configuration element.</li> + <li><strong>directory</strong> - The directory name for the web + application context in the Host's application base directory.</li> + <li><strong>webapp.war</strong> - The name of a web application war file + located in the Host's application base directory.</li> + </ul></li> +</ul> + +<p>Each command will return a response in <code>text/plain</code> format +(i.e. plain ASCII with no HTML markup), making it easy for both humans and +programs to read). The first line of the response will begin with either +<code>OK</code> or <code>FAIL</code>, indicating whether the requested +command was successful or not. In the case of failure, the rest of the first +line will contain a description of the problem that was encountered. Some +commands include additional lines of information as described below.</p> + +<p><em>Internationalization Note</em> - The Manager application looks up +its message strings in resource bundles, so it is possible that the strings +have been translated for your platform. The examples below show the English +version of the messages.</p> + +<blockquote> +<p><em><strong>WARNING:</strong> the legacy commands <code>/install</code> and +<code>/remove</code> are deprecated. +They are presently equivalent to <code>/deploy</code> and <code>/undeploy</code>, +but could be removed in a future release.</em></p> +</blockquote> + +<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Deploy A New Application Remotely"><!--()--></a><a name="Deploy_A_New_Application_Remotely"><strong>Deploy A New Application Remotely</strong></a></font></td></tr><tr><td><blockquote> + +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +http://localhost:8080/manager/deploy?path=/foo +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + +<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> +directory of our corresponding virtual host, and start , using the directory +name or the war file name without the .war extension as the path. The +application can later be undeployed (and the corresponding application directory +removed) by use of the <code>/undeploy</code> command.</p> + +<p>The .WAR file may include Tomcat specific deployment configuration, by +including a Context configuration XML file in +<code>/META-INF/context.xml</code>.</p> + +<p>URL parameters include:</p> +<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 + be later redeployed when needed using only the tag.</li> +</ul> + +<p><strong>NOTE</strong> - This command is the logical +opposite of the <code>/undeploy</code> command.</p> + +<p>If installation and startup is successful, you will receive a response +like this:</p> +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +OK - Deployed application at context path /foo +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + +<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 + 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 + application before performing the deployment.</p> + </blockquote></li> +<li><em>Encountered exception</em> + <blockquote> + <p>An exception was encountered trying to start the new web application. + Check the Tomcat 6 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> +</ul> + +</blockquote></td></tr></table> + +<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Deploy A New Application from a Local Path"><!--()--></a><a name="Deploy_A_New_Application_from_a_Local_Path"><strong>Deploy A New Application from a Local Path</strong></a></font></td></tr><tr><td><blockquote> + +<p>Deploy and start a new web application, attached to the specified context +<code>path</code> (which must not be in use by any other web application). +This command is the logical opposite of the <code>/undeploy</code> command.</p> + +<p>There are a number of different ways the deploy command can be used.</p> + +<h3>Deploy a version of a previously deployed webapp</h3> + +<p>This can be used to deploy a previous version of a 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> +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +http://localhost:8080/manager/deploy?path=/footoo&tag=footag +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + + +<h3>Deploy a Directory or WAR by URL</h3> + +<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 +name without the ".war" extension is used as the path. The <code>war</code> +parameter specifies a URL (including the <code>file:</code> scheme) for either +a directory or a web application archive (WAR) file. The supported syntax for +a URL referring to a WAR file is described on the Javadocs page for the +<code>java.net.JarURLConnection</code> class. Use only URLs that refer to +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> +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +http://localhost:8080/manager/deploy?path=/footoo&war=file:/path/to/foo +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + + +<p>In this example the ".war" file <code>/path/to/bar.war</code> on the +Tomcat server is deployed as the web application context named +<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> +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +http://localhost:8080/manager/deploy?war=jar:file:/path/to/bar.war!/ +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + + +<h3>Deploy a Directory or War from the Host appBase</h3> + +<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" +extension is used as the path.</p> + +<p>In this example the web application located in a sub directory named +<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> +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +http://localhost:8080/manager/deploy?war=foo +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + + +<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> +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +http://localhost:8080/manager/deploy?war=bar.war +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + + +<h3>Deploy using a Context configuration ".xml" file</h3> + +<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 +".war" file or web application directory. The context <code>path</code> +is not used when deploying a web application using a context ".xml" +configuration file.</p> + +<p>A Context configuration ".xml" file can contain valid XML for a +web application Context just as if it were configured in your +Tomcat <code>server.xml</code> configuration file. Here is an +example:</p> +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +<Context path="/foobar" docBase="/path/to/application/foobar" + debug="0"> + + <!-- Link to the user database we will get roles from --> + <ResourceLink name="users" global="UserDatabase" + type="org.apache.catalina.UserDatabase"/> + +</Context> +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + + +<p>When the optional <code>war</code> parameter is set to the URL +for a web application ".war" file or directory it overrides any +docBase configured in the context configuration ".xml" file.</p> + +<p>Here is an example of deploying an application using a Context +configuration ".xml" file.</p> +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +http://localhost:8080/manager/deploy?config=file:/path/context.xml +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + + +<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> +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +http://localhost:8080/manager/deploy?config=file:/path/context.xml&war=jar:file:/path/bar.war!/ +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + + +<h3>Deployment Notes</h3> + +<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 +directory.</p> + +<p>If the application war or directory is installed in your Host appBase +directory and either the Host is configured with autoDeploy=true or +liveDeploy=true, the Context path must match the directory name or +war file name without the ".war" extension.</p> + +<p>For security when untrusted users can manage web applications, the +Host deployXML flag can be set to false. This prevents untrusted users +from deploying web applications using a configuration XML file and +also prevents them from deploying application directories or ".war" +files located outside of their Host appBase.</p> + + +<h3>Deploy Response</h3> + +<p>If installation and startup is successful, you will receive a response +like this:</p> +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +OK - Deployed application at context path /foo +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + +<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 + 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 + application before performing the deployment.</p> + </blockquote></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><em>Encountered exception</em> + <blockquote> + <p>An exception was encountered trying to start the new web application. + Check the Tomcat 6 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><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><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><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 + directory and either the Host is configured with autoDeploy=true or + liveDeploy=true, the Context path must match the directory name or + war file name without the ".war" extension. + </blockquote></li> +<li><em>Only web applications in the Host web application directory can + be installed</em> + <blockquote> + 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> +</ul> + +</blockquote></td></tr></table> + +<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="List Currently Deployed Applications"><!--()--></a><a name="List_Currently_Deployed_Applications"><strong>List Currently Deployed Applications</strong></a></font></td></tr><tr><td><blockquote> + +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +http://localhost:8080/manager/list +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + +<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> +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +OK - Listed applications for virtual host localhost +/webdav:running:0 +/examples:running:0 +/manager:running:0 +/:running:0 +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + +</blockquote></td></tr></table> + +<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Reload An Existing Application"><!--()--></a><a name="Reload_An_Existing_Application"><strong>Reload An Existing Application</strong></a></font></td></tr><tr><td><blockquote> + +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +http://localhost:8080/manager/reload?path=/examples +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + +<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 +updated classes or property files in the <code>/WEB-INF/classes</code> +directory or when you have added or updated jar files in the +<code>/WEB-INF/lib</code> directory. +</p> +<p><strong>NOTE:</strong> The <code>/WEB-INF/web.xml</code> +web application configuration file is not reread on a reload. +If you have made changes to your web.xml file you must stop +then start the web application. +</p> + +<p>If this command succeeds, you will see a response like this:</p> +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +OK - Reloaded application at context path /examples +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + +<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 6 logs for the details.</p> + </blockquote></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><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><em>No context path was specified</em> + <blockquote> + The <code>path</code> parameter is required. + </blockquote></li> +<li><em>Reload not supported on WAR deployed at path /foo</em> + <blockquote> + 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 + is deployed from an unpacked directory. If you are using a WAR file, + 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> +</ul> + +</blockquote></td></tr></table> + +<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="List OS and JVM Properties"><!--()--></a><a name="List_OS_and_JVM_Properties"><strong>List OS and JVM Properties</strong></a></font></td></tr><tr><td><blockquote> + +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +http://localhost:8080/manager/serverinfo +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + +<p>Lists information about the Tomcat version, OS, and JVM properties.</p> + +<p>If an error occurs, 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 enumerate the system properties. + Check the Tomcat 6 logs for the details.</p> + </blockquote></li> +</ul> + +</blockquote></td></tr></table> + +<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="List Available Global JNDI Resources"><!--()--></a><a name="List_Available_Global_JNDI_Resources"><strong>List Available Global JNDI Resources</strong></a></font></td></tr><tr><td><blockquote> + +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +http://localhost:8080/manager/resources[?type=xxxxx] +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + +<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> +request parameter, the value must be the fully qualified Java class name of +the resource type you are interested in (for example, you would specify +<code>javax.sql.DataSource</code> to acquire the names of all available +JDBC data sources). If you do not specify the <code>type</code> request +parameter, resources of all types will be returned.</p> + +<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> +<p>or</p> +<pre> + OK - Listed global resources of type xxxxx +</pre> +<p>followed by one line for each resource. Each line is composed of fields +delimited by colon characters (":"), as follows:</p> +<ul> +<li><em>Global Resource Name</em> - The name of this global JNDI resource, + which would be used in the <code>global</code> attribute of a + <code><ResourceLink></code> element.</li> +<li><em>Global Resource Type</em> - The fully qualified Java class name of + this global JNDI resource.</li> +</ul> + +<p>If an error occurs, 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 enumerate the global JNDI + resources. Check the Tomcat 6 logs for the details.</p> + </blockquote></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> +</ul> + + +</blockquote></td></tr></table> + + +<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="List Available Security Roles"><!--()--></a><a name="List_Available_Security_Roles"><strong>List Available Security Roles</strong></a></font></td></tr><tr><td><blockquote> + +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +http://localhost:8080/manager/roles +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + +<p>List the security role names (and corresponding descriptions) that are +available in the <code>org.apache.catalina.UserDatabase</code> resource that +is linked to the <code>users</code> resource reference in the web.xml file +for the Manager web application. This would typically be used, for example, +by a deployment tool that wanted to create +<code><security-role-ref></code> elements to map security role names +used in a web application to the role names actually defined within the +container.</p> + +<p>By default, the <code>users</code> resource reference is pointed at the +global <code>UserDatabase</code> resource. If you choose to utilize a +different user database per virtual host, you should modify the +<code><ResourceLink></code> element in the default +<code>manager.xml</code> context configuration file to point at the global +user database resource for this virtual host.</p> + +<p>When this command is executed, the first line of the response will be:</p> +<pre> + OK - Listed security roles +</pre> +<p>followed by one line for each security role. Each line is composed of +fields delimited by colon characters (":") as follows:</p> +<ul> +<li><em>Security Role Name</em> - A security role name that is known to Tomcat + in the user database.</li> +<li><em>Description</em> - Description of this security role (useful in + creating user interfaces for selecting roles.</li> +</ul> + +<p>If an error occurs, the response will start with <code>FAIL</code> and +include an error message. Possible causes for problems include:</p> +<ul> +<li><em>Cannot resolve user database reference</em> - A JNDI error prevented + the successful lookup of the <code>org.apache.catalina.UserDatabase</code> + resource. Check the Tomcat log files for a stack trace associated with + this error.</li> +<li><em>No user database is available</em> - You have not configured a resource + reference for the <code>users</code> resource that points at an + appropriate user database instance. Check your <code>manager.xml</code> + file and ensure that you have created an appropriate + <code><ResourceLink></code> or + <code><ResourceParams></code> element for this resource.</li> +</ul> + +</blockquote></td></tr></table> + + +<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Session Statistics"><!--()--></a><a name="Session_Statistics"><strong>Session Statistics</strong></a></font></td></tr><tr><td><blockquote> + +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +http://localhost:8080/manager/sessions?path=/examples +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + +<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> +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +OK - Session information for application at context path /examples +Default maximum session inactive interval 30 minutes +30 - <40 minutes:1 sessions +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + +</blockquote></td></tr></table> + + +<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Start an Existing Application"><!--()--></a><a name="Start_an_Existing_Application"><strong>Start an Existing Application</strong></a></font></td></tr><tr><td><blockquote> + +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +http://localhost:8080/manager/start?path=/examples +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + +<p>Signal a stopped application to restart, and make itself available again. +Stopping and starting is useful, for example, if the database required by +your application becomes temporarily unavailable. It is usually better to +stop the web application that relies on this database rather than letting +users continuously encounter database exceptions.</p> + +<p>If this command succeeds, you will see a response like this:</p> +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +OK - Started application at context path /examples +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + +<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 6 logs for the details.</p> + </blockquote></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><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><em>No context path was specified</em> + <blockquote> + The <code>path</code> parameter is required. + </blockquote></li> +</ul> + +</blockquote></td></tr></table> + +<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Stop an Existing Application"><!--()--></a><a name="Stop_an_Existing_Application"><strong>Stop an Existing Application</strong></a></font></td></tr><tr><td><blockquote> + +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +http://localhost:8080/manager/stop?path=/examples +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + +<p>Signal an existing application to make itself unavailable, but leave it +deployed. Any request that comes in while an application is +stopped will see an HTTP error 404, and this application will show as +"stopped" on a list applications command.</p> + +<p>If this command succeeds, you will see a response like this:</p> +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +OK - Stopped application at context path /examples +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + +<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 6 logs for the details.</p> + </blockquote></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><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><em>No context path was specified</em> + <blockquote> + The <code>path</code> parameter is required. + </blockquote></li> +</ul> + +</blockquote></td></tr></table> + + +<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Undeploy an Existing Application"><!--()--></a><a name="Undeploy_an_Existing_Application"><strong>Undeploy an Existing Application</strong></a></font></td></tr><tr><td><blockquote> + +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +http://localhost:8080/manager/undeploy?path=/examples +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + +<p><strong><font color="red">WARNING</font> - 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, +the application directory resulting either from a deploy in unpacked form +or from .WAR expansion as well as the XML Context definition from +<code>$CATALINA_BASE/conf/[enginename]/[hostname]/</code> directory. +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 +remove it from Tomcat (which also makes this context path available for +reuse later). In addition, the document root directory is removed, if it +exists in the <code>appBase</code> directory (typically "webapps") for +this virtual host. This command is the logical opposite of the +<code>/deploy</code> command.</p> + +<p>If this command succeeds, you will see a response like this:</p> +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +OK - Undeployed application at context path /examples +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + +<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 6 logs for the details.</p> + </blockquote></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><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><em>No context path was specified</em> + <blockquote> + The <code>path</code> parameter is required. + </blockquote></li> +</ul> + +</blockquote></td></tr></table> + +<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Finding memory leaks"><!--()--></a><a name="Finding_memory_leaks"><strong>Finding memory leaks</strong></a></font></td></tr><tr><td><blockquote> + +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +http://localhost:8080/manager/findleaks +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + +<p><strong>The find leaks diagnostic triggers a full garbage collection. It +should be used with extreme caution on production systems.</strong></p> + +<p>The find leaks diagnostic attempts to identify web applications that have +caused memory leaks when they were stopped, reloaded or undeployed. Results +should always be confirmed +with a profiler. The diagnostic uses additional functionality provided by the +StandardHost implementation. It will not work if a custom host is used that +does not extend StandardHost.</p> + +<p>Explicitly triggering a full garbage collection from Java code is documented +to be unreliable. Furthermore, depending on the JVM used, there are options to +disable explicit GC triggering, like <code>-XX:+DisableExplicitGC</code>. +If you want to make sure, that the diagnostics were successfully running a full 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> +<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> +/leaking-webapp +</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" alt="" src="./images/void.gif"></td></tr></table></div> + +<p>Each context path for a web application that was stopped, reloaded or +undeployed, but which classes from the previous runs are still loaded in memory, +thus causing a memory leak, will be listed on a new line. If an application +has been reloaded several times, it may be listed several times.</p> + +<p>If the command does not succeed, the response will start with +<code>FAIL</code> and include an error message.</p> + +</blockquote></td></tr></table> + +<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Server Status"><!--()--></a><a name="Server_Status"><strong>Server Status</strong></a></font></td></tr><tr><td><blockquote> + +<p>From this link , you can view information about the server.</p> + +<p>First, you have the server and JVM version number, JVM provider, OS name +and number followed by the architecture type.</p> + +<p>Second, there is several information about the memory usage of the JVM +(available, total and max memory).</p> + +<p>Then, there is information about the Tomcat AJP and HTTP connectors. +The same information is available for both of them : +</p> +<ul> + <li><p>Threads information : Max threads, min and max spare threads, + current thread count and current thread busy.</p></li> + <li><p>Request information : Max processing time and processing time, + request and error count, bytes received and sent.</p></li> + <li><p>A table showing Stage, Time, Bytes Sent, Bytes Receive, Client, + VHost and Request. All existing threads are listed in the table. + Here is the list of the possible thread stages :</p> + <ul> + <li><p><em>"Parse and Prepare Request"</em> : The request headers are + being parsed or the necessary preparation to read the request body (if + a transfer encoding has been specified) is taking place.</p></li> + <li><p><em>"Service"</em> : The thread is processing a request and + generating the response. This stage follows the "Parse and Prepare + Request" stage and precedes the "Finishing" stage. There is always at + least one thread in this stage (the server-status page).</p></li> + <li><p><em>"Finishing"</em> : The end of the request processing. Any + remainder of the response still in the output buffers is sent to the + client. This stage is followed by "Keep-Alive" if it is appropriate to + keep the connection alive or "Ready" if "Keep-Alive" is not + appropriate.</p></li> + <li><p><em>"Keep-Alive"</em> : The thread keeps the connection open to + the client in case the client sends another request. If another request + is recieved, the next stage will br "Parse and Prepare Requst". If no + request is received before the keep alive times out, the connection will + be closed and the next stage will be "Ready".</p></li> + <li><p><em>"Ready"</em> : The thread is at rest and ready to be + used.</p></li> + </ul> + </li> +</ul> +</blockquote></td></tr></table> + +</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Executing Manager Commands With Ant"><!--()--></a><a name="Executing_Manager_Commands_With_Ant"><strong>Executing Manager Commands With Ant</strong></a></font></td></tr><tr><td><blockquote> + +<p>In addition to the ability to execute Manager commands via HTTP requests, +as documented above, Tomcat 6 includes a convenient set of Task definitions +for the <em>Ant</em> (version 1.4 or later) build tool. In order to use these +commands, you must perform the following setup operations:</p> +<ul> +<li>Download the binary distribution of Ant from + <a href="http://ant.apache.org";>http://ant.apache.org</a>. + You must use version <strong>1.4</strong> or later.</li> +<li>Install the Ant distribution in a convenient directory (called + ANT_HOME in the remainder of these instructions).</li> +<li>Copy the file <code>server/lib/catalina-ant.jar</code> from your Tomcat 6 + installation into Ant's library directory (<code>$ANT_HOME/lib</code>). + </li> +<li>Add the <code>$ANT_HOME/bin</code> directory to your <code>PATH</code> + environment variable.</li> +<li>Configure at least one username/password combination in your Tomcat + user database that includes the <code>manager</code> role.</li> +</ul> + +<p>To use custom tasks within Ant, you must declare them first with a +<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"/> + <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="resources" classname="org.apache.catalina.ant.ResourcesTask"/> + <taskdef name="roles" classname="org.apache.catalina.ant.RolesTask"/> + <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
<TRUNCATED>
