WebSVN - Integrator Subversion - Blame - Rev 771 - /projeto-trade/apache-tomcat-9.0.112/webapps/docs/manager-howto.html

Rev	Author	Line No.	Line
771	blopes	1	<!DOCTYPE html SYSTEM "about:legacy-compat">
		2	<html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><link href="./images/docs-stylesheet.css" rel="stylesheet" type="text/css"><title>Apache Tomcat 9 (9.0.112) - Manager App How-To</title></head><body><div id="wrapper"><header><div id="header"><div><div><div class="logo noPrint"><a href="https://tomcat.apache.org/"><img alt="Tomcat Home" src="./images/tomcat.png"></a></div><div style="height: 1px;"></div><div class="asfLogo noPrint"><a href="https://www.apache.org/" target="_blank"><img src="./images/asf-logo.svg" alt="The Apache Software Foundation" style="width: 266px; height: 83px;"></a></div><h1>Apache Tomcat 9</h1><div class="versionInfo">
		3	Version 9.0.112,
		4	<time datetime="2025-11-06">Nov 6 2025</time></div><div style="height: 1px;"></div><div style="clear: left;"></div></div></div></div></header><div id="middle"><div><div id="mainLeft" class="noprint"><div><nav><div><h2>Links</h2><ul><li><a href="index.html">Docs Home</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/FAQ">FAQ</a></li></ul></div><div><h2>User Guide</h2><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="host-manager-howto.html">6) Host Manager</a></li><li><a href="realm-howto.html">7) Realms and AAA</a></li><li><a href="security-manager-howto.html">8) Security Manager</a></li><li><a href="jndi-resources-howto.html">9) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">10) JDBC DataSources</a></li><li><a href="class-loader-howto.html">11) Classloading</a></li><li><a href="jasper-howto.html">12) JSPs</a></li><li><a href="ssl-howto.html">13) SSL/TLS</a></li><li><a href="ssi-howto.html">14) SSI</a></li><li><a href="cgi-howto.html">15) CGI</a></li><li><a href="proxy-howto.html">16) Proxy Support</a></li><li><a href="mbeans-descriptors-howto.html">17) MBeans Descriptors</a></li><li><a href="default-servlet.html">18) Default Servlet</a></li><li><a href="cluster-howto.html">19) Clustering</a></li><li><a href="balancer-howto.html">20) Load Balancer</a></li><li><a href="connectors.html">21) Connectors</a></li><li><a href="monitoring.html">22) Monitoring and Management</a></li><li><a href="logging.html">23) Logging</a></li><li><a href="apr.html">24) APR/Native</a></li><li><a href="virtual-hosting-howto.html">25) Virtual Hosting</a></li><li><a href="aio.html">26) Advanced IO</a></li><li><a href="maven-jars.html">27) Mavenized</a></li><li><a href="security-howto.html">28) Security Considerations</a></li><li><a href="windows-service-howto.html">29) Windows Service</a></li><li><a href="windows-auth-howto.html">30) Windows Authentication</a></li><li><a href="jdbc-pool.html">31) Tomcat's JDBC Pool</a></li><li><a href="web-socket-howto.html">32) WebSocket</a></li><li><a href="rewrite.html">33) Rewrite</a></li><li><a href="cdi.html">34) CDI 2 and JAX-RS</a></li><li><a href="graal.html">35) AOT/GraalVM Support</a></li></ul></div><div><h2>Reference</h2><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">Tomcat Javadocs</a></li><li><a href="servletapi/index.html">Servlet 4.0 Javadocs</a></li><li><a href="jspapi/index.html">JSP 2.3 Javadocs</a></li><li><a href="elapi/index.html">EL 3.0 Javadocs</a></li><li><a href="websocketapi/index.html">WebSocket 1.1 Javadocs</a></li><li><a href="jaspicapi/index.html">JASPIC 1.1 Javadocs</a></li><li><a href="annotationapi/index.html">Common Annotations 1.3 Javadocs</a></li><li><a href="https://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul></div><div><h2>Apache Tomcat Development</h2><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/Tomcat+Versions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="tribes/introduction.html">Tribes</a></li></ul></div></nav></div></div><div id="mainRight"><div id="content"><h2>Manager App How-To</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
		5	<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Configuring_Manager_Application_Access">Configuring Manager Application Access</a></li><li><a href="#HTML_User-friendly_Interface">HTML User-friendly Interface</a></li><li><a href="#Supported_Manager_Commands">Supported Manager Commands</a><ol><li><a href="#Common_Parameters">Common Parameters</a></li><li><a href="#Deploy_A_New_Application_Archive_(WAR)_Remotely">Deploy A New Application Archive (WAR) Remotely</a></li><li><a href="#Deploy_A_New_Application_from_a_Local_Path">Deploy A New Application from a Local Path</a><ol><li><a href="#Deploy_a_previously_deployed_webapp">Deploy a previously deployed webapp</a></li><li><a href="#Deploy_a_Directory_or_WAR_by_URL">Deploy a Directory or WAR by URL</a></li><li><a href="#Deploy_a_Directory_or_War_from_the_Host_appBase">Deploy a Directory or War from the Host appBase</a></li><li><a href="#Deploy_using_a_Context_configuration_%22.xml%22_file">Deploy using a Context configuration ".xml" file</a></li><li><a href="#Deployment_Notes">Deployment Notes</a></li><li><a href="#Deploy_Response">Deploy Response</a></li></ol></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="#Session_Statistics">Session Statistics</a></li><li><a href="#Expire_Sessions">Expire Sessions</a></li><li><a href="#Start_an_Existing_Application">Start an Existing Application</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="#Connector_SSL/TLS_cipher_information">Connector SSL/TLS cipher information</a></li><li><a href="#Connector_SSL/TLS_certificate_chain_information">Connector SSL/TLS certificate chain information</a></li><li><a href="#Connector_SSL/TLS_trusted_certificate_information">Connector SSL/TLS trusted certificate information</a></li><li><a href="#Reload_TLS_configuration">Reload TLS configuration</a></li><li><a href="#Thread_Dump">Thread Dump</a></li><li><a href="#VM_Info">VM Info</a></li><li><a href="#Save_Configuration">Save Configuration</a></li></ol></li><li><a href="#Server_Status">Server Status</a></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_Get_command">JMX Get command</a></li><li><a href="#JMX_Set_command">JMX Set command</a></li><li><a href="#JMX_Invoke_command">JMX Invoke command</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></ul>
		6	</div><h3 id="Introduction">Introduction</h3><div class="text">
		7
		8	<p>In many production environments, it is very useful to have the capability
		9	to deploy a new web application, or undeploy an existing one, without having
		10	to shut down and restart the entire container. In addition, you can request
		11	an existing application to reload itself, even if you have not declared it
		12	to be <code>reloadable</code> in the Tomcat server
		13	configuration file.</p>
		14
		15	<p>To support these capabilities, Tomcat includes a web application
		16	(installed by default on context path <code>/manager</code>) that supports
		17	the following functions:</p>
		18	<ul>
		19	<li>Deploy a new web application from the uploaded contents of a WAR file.</li>
		20	<li>Deploy a new web application, on a specified context path, from the
		21	server file system.</li>
		22	<li>List the currently deployed web applications, as well as the
		23	sessions that are currently active for those web apps.</li>
		24	<li>Reload an existing web application, to reflect changes in the
		25	contents of <code>/WEB-INF/classes</code> or <code>/WEB-INF/lib</code>.
		26	</li>
		27	<li>List the OS and JVM property values.</li>
		28	<li>List the available global JNDI resources, for use in deployment
		29	tools that are preparing <code><ResourceLink></code> elements
		30	nested in a <code><Context></code> deployment description.</li>
		31	<li>Start a stopped application (thus making it available again).</li>
		32	<li>Stop an existing application (so that it becomes unavailable), but
		33	do not undeploy it.</li>
		34	<li>Undeploy a deployed web application and delete its document base
		35	directory (unless it was deployed from file system).</li>
		36	</ul>
		37
		38	<p>A default Tomcat installation includes an instance of the Manager application
		39	configured for the default virtual host. If you create additional virtual hosts,
		40	you may wish to add an instance of the Manager application to one or more of
		41	those Hosts. To add an instance of the Manager web application
		42	<code>Context</code> to a new host install the <code>manager.xml</code> context
		43	configuration file in the
		44	<code>$CATALINA_BASE/conf/[enginename]/[hostname]</code> folder. Here is an
		45	example:</p>
		46	<div class="codeBox"><pre><code><Context privileged="true" antiResourceLocking="false"
		47	docBase="${catalina.home}/webapps/manager">
		48	<CookieProcessor className="org.apache.tomcat.util.http.Rfc6265CookieProcessor"
		49	sameSiteCookies="strict" />
		50	<Valve className="org.apache.catalina.valves.RemoteCIDRValve"
		51	allow="127.0.0.0/8,::1/128" />
		52	<Manager sessionAttributeValueClassNameFilter="java\.lang\.(?:Boolean\|Integer\|Long\|Number\|String)\|org\.apache\.catalina\.filters\.CsrfPreventionFilter\$LruCache(?:\$1)?\|java\.util\.(?:Linked)?HashMap"/>
		53	</Context></code></pre></div>
		54
		55	<p>There are three ways to use the <strong>Manager</strong> web application.</p>
		56	<ul>
		57	<li>As an application with a user interface you use in your browser.
		58	Here is an example URL where you can replace <code>localhost</code> with
		59	your website host name: <code>http://localhost:8080/manager/html</code> .</li>
		60	<li>A minimal version using HTTP requests only which is suitable for use
		61	by scripts setup by system administrators. Commands are given as part of the
		62	request URI, and responses are in the form of simple text that can be easily
		63	parsed and processed. See <a href="#Supported_Manager_Commands">
		64	Supported Manager Commands</a> for more information.</li>
		65	<li>A convenient set of task definitions for the <em>Ant</em>
		66	(version 1.4 or later) build tool. See
		67	<a href="#Executing_Manager_Commands_With_Ant">Executing Manager Commands
		68	With Ant</a> for more information.</li>
		69	</ul>
		70
		71	</div><h3 id="Configuring_Manager_Application_Access">Configuring Manager Application Access</h3><div class="text">
		72
		73
		74	<p><em>The description below uses the variable name $CATALINA_BASE to refer the
		75	base directory against which most relative paths are resolved. If you have
		76	not configured Tomcat for multiple instances by setting a CATALINA_BASE
		77	directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
		78	the directory into which you have installed Tomcat.</em></p>
		79
		80
		81	<p>It would be quite unsafe to ship Tomcat with default settings that allowed
		82	anyone on the Internet to execute the Manager application on your server.
		83	Therefore, the Manager application is shipped with the requirement that anyone
		84	who attempts to use it must authenticate themselves, using a username and
		85	password that have one of <strong>manager-xxx</strong> roles associated with
		86	them (the role name depends on what functionality is required).
		87	Further, there is no username in the default users file
		88	(<code>$CATALINA_BASE/conf/tomcat-users.xml</code>) that is assigned to those
		89	roles. Therefore, access to the Manager application is completely disabled
		90	by default.</p>
		91
		92	<p>You can find the role names in the <code>web.xml</code> file of the Manager
		93	web application. The available roles are:</p>
		94
		95	<ul>
		96	<li><strong>manager-gui</strong> — Access to the HTML interface.</li>
		97	<li><strong>manager-status</strong> — Access to the "Server Status"
		98	page only.</li>
		99	<li><strong>manager-script</strong> — Access to the tools-friendly
		100	plain text interface that is described in this document,
		101	and to the "Server Status" page.</li>
		102	<li><strong>manager-jmx</strong> — Access to JMX proxy interface
		103	and to the "Server Status" page.</li>
		104	</ul>
		105
		106	<p>The HTML interface is protected against CSRF (Cross-Site Request Forgery)
		107	attacks, but the text and JMX interfaces cannot be protected. It means that
		108	users who are allowed access to the text and JMX interfaces have to be cautious
		109	when accessing the Manager application with a web browser.
		110	To maintain the CSRF protection:</p>
		111
		112	<ul>
		113	<li>If you use web browser to access the Manager application using
		114	a user that has either <strong>manager-script</strong> or
		115	<strong>manager-jmx</strong> roles (for example for testing
		116	the plain text or JMX interfaces), you MUST close all windows
		117	of the browser afterwards to terminate the session.
		118	If you do not close the browser and visit other sites, you may become
		119	victim of a CSRF attack.</li>
		120	<li>It is recommended to never grant
		121	the <strong>manager-script</strong> or <strong>manager-jmx</strong>
		122	roles to users that have the <strong>manager-gui</strong> role.</li>
		123	</ul>
		124
		125	<p><strong>Note</strong> that JMX proxy interface is effectively low-level root-like
		126	administrative interface of Tomcat. One can do a lot, if one knows
		127	what commands to call. You should be cautious when enabling the
		128	<strong>manager-jmx</strong> role.</p>
		129
		130	<p>To enable access to the Manager web application, you must either create
		131	a new username/password combination and associate one of the
		132	<strong>manager-xxx</strong> roles with it, or add a
		133	<strong>manager-xxx</strong> role
		134	to some existing username/password combination.
		135	As the majority of this document describes the using the text interface, this
		136	example will use the role name <strong>manager-script</strong>.
		137	Exactly how the usernames/passwords are configured depends on which
		138	<a href="config/realm.html">Realm implementation</a> you are using:</p>
		139	<ul>
		140	<li><em>UserDatabaseRealm</em> plus <em>MemoryUserDatabase</em>, or <em>MemoryRealm</em>
		141	— The <em>UserDatabaseRealm</em> and <em>MemoryUserDatabase</em> are
		142	configured in the default <code>$CATALINA_BASE/conf/server.xml</code>.
		143	Both <em>MemoryUserDatabase</em> and <em>MemoryRealm</em> read an
		144	XML-format file by default stored at
		145	<code>$CATALINA_BASE/conf/tomcat-users.xml</code>, which can be
		146	edited with any text editor. This file contains an XML
		147	<code><user></code> for each individual user, which might
		148	look something like this:
		149	<div class="codeBox"><pre><code><user username="craigmcc" password="secret" roles="standard,manager-script" /></code></pre></div>
		150	which defines the username and password used by this individual to
		151	log on, and the role names they are associated with. You can
		152	add the <strong>manager-script</strong> role to the comma-delimited
		153	<code>roles</code> attribute for one or more existing users, and/or
		154	create new users with that assigned role.</li>
		155	<li><em>DataSourceRealm</em> or <em>JDBCRealm</em>
		156	— Your user and role information is stored in
		157	a database accessed via JDBC. Add the <strong>manager-script</strong> role
		158	to one or more existing users, and/or create one or more new users
		159	with this role assigned, following the standard procedures for your
		160	environment.</li>
		161	<li><em>JNDIRealm</em> — Your user and role information is stored in
		162	a directory server accessed via LDAP. Add the
		163	<strong>manager-script</strong> role to one or more existing users,
		164	and/or create one or more new users with this role assigned, following
		165	the standard procedures for your environment.</li>
		166	</ul>
		167
		168	<p>The first time you attempt to issue one of the Manager commands
		169	described in the next section, you will be challenged to log on using
		170	BASIC authentication. The username and password you enter do not matter,
		171	as long as they identify a valid user in the users database who possesses
		172	the role <strong>manager-script</strong>.</p>
		173
		174	<p>In addition to the password restrictions, access to the Manager web
		175	application can be restricted by the <strong>remote IP address</strong> or host
		176	by adding a <code>RemoteCIDRValve</code> or <code>RemoteHostValve</code>.
		177	See <a href="config/valve.html#Remote_Address_Filter">valves documentation</a>
		178	for details. Here is
		179	an example of restricting access to the localhost by IP address:</p>
		180	<div class="codeBox"><pre><code><Context privileged="true">
		181	<Valve className="org.apache.catalina.valves.RemoteCIDRValve"
		182	allow="127.0.0.0/8,::1/128" />
		183	</Context></code></pre></div>
		184
		185	</div><h3 id="HTML_User-friendly_Interface">HTML User-friendly Interface</h3><div class="text">
		186
		187	<p>The user-friendly HTML interface of Manager web application is located at</p>
		188
		189	<div class="codeBox"><pre><code>http://{host}:{port}/manager/html</code></pre></div>
		190
		191	<p>As has already been mentioned above, you need <strong>manager-gui</strong>
		192	role to be allowed to access it. There is a separate document that provides
		193	help on this interface. See:</p>
		194
		195	<ul>
		196	<li><a href="html-manager-howto.html">HTML Manager documentation</a></li>
		197	</ul>
		198
		199	<p>The HTML interface is protected against CSRF (Cross-Site Request Forgery)
		200	attacks. Each access to the HTML pages generates a random token, which is
		201	stored in your session and is included in all links on the page. If your next
		202	action does not have correct value of the token, the action will be denied.
		203	If the token has expired you can start again from the main page or
		204	<em>List Applications</em> page of Manager.</p>
		205
		206	<p>To customize the subtitle of the HTML interface of the Manager web application,
		207	you can add any valid xml escaped html code to the <code>htmlSubTitle</code>
		208	initialisation parameter of the <code>HTMLManagerServlet</code>
		209	</p>
		210
		211	<div class="codeBox"><pre><code><servlet>
		212	<servlet-name>HTMLManager</servlet-name>
		213	<servlet-class>org.apache.catalina.manager.HTMLManagerServlet</servlet-class>
		214	<init-param>
		215	<param-name>htmlSubTitle</param-name>
		216	<param-value>Company Inc.&lt;br&gt;&lt;i style=&apos;color:red&apos;&gt;Staging&lt;/i&gt;</param-value>
		217	</init-param>
		218	...
		219	</servlet></code></pre></div>
		220
		221	<p>The above string value would unescape and be appended to the title</p>
		222
		223	<div class="codeBox"><pre><code>Company Inc.<br><i style='color:red'>Staging</i></code></pre></div>
		224
		225	</div><h3 id="Supported_Manager_Commands">Supported Manager Commands</h3><div class="text">
		226
		227	<p>All commands that the Manager application knows how to process are
		228	specified in a single request URI like this:</p>
		229	<div class="codeBox"><pre><code>http://{host}:{port}/manager/text/{command}?{parameters}</code></pre></div>
		230	<p>where <code>{host}</code> and <code>{port}</code> represent the hostname
		231	and port number on which Tomcat is running, <code>{command}</code>
		232	represents the Manager command you wish to execute, and
		233	<code>{parameters}</code> represents the query parameters
		234	that are specific to that command. In the illustrations below, customize
		235	the host and port appropriately for your installation.</p>
		236
		237	<p>The commands are usually executed by HTTP GET requests. The
		238	<code>/deploy</code> command has a form that is executed by an HTTP PUT request.</p>
		239
		240	<div class="subsection"><h4 id="Common_Parameters">Common Parameters</h4><div class="text">
		241
		242	<p>Most commands accept one or more of the following query parameters:</p>
		243	<ul>
		244	<li><strong>path</strong> - The context path (including the leading slash)
		245	of the web application you are dealing with. To select the ROOT web
		246	application, specify "/".
		247	<br>
		248	<strong>NOTE</strong>: It is not possible to perform administrative commands
		249	on the Manager application itself.
		250	<br>
		251	<strong>NOTE</strong>: If the path parameter is not explicitly specified
		252	then the path and the version will be derived using the standard
		253	<a href="config/context.html#Naming">Context naming</a> rules from the
		254	config parameter or, if the config parameter is not present, the war
		255	parameter.</li>
		256	<li><strong>version</strong> - The version of this web application as used by
		257	the <a href="config/context.html">parallel deployment</a> feature. If you
		258	use parallel deployment wherever a path is required you must specify a
		259	version in addition to the path and it is the combination of path and
		260	version that must be unique rather than just the path.
		261	<br>
		262	<strong>NOTE</strong>: If the path is not explicitly specified, the version
		263	parameter is ignored.</li>
		264	<li><strong>war</strong> - URL of a web application archive (WAR) file, or
		265	pathname of a directory which contains the web application, or a
		266	Context configuration ".xml" file. You can use URLs in any of the
		267	following formats:
		268	<ul>
		269	<li><strong>file:/absolute/path/to/a/directory</strong> - The absolute
		270	path of a directory that contains the unpacked version of a web
		271	application. This directory will be attached to the context path
		272	you specify without any changes.</li>
		273	<li><strong>file:/absolute/path/to/a/webapp.war</strong> - The absolute
		274	path of a web application archive (WAR) file. This is valid
		275	<strong>only</strong> for the <code>/deploy</code> command, and is
		276	the only acceptable format to that command.</li>
		277	<li><strong>file:/absolute/path/to/a/context.xml</strong> - The
		278	absolute path of a web application Context configuration ".xml"
		279	file which contains the Context configuration element.</li>
		280	<li><strong>directory</strong> - The directory name for the web
		281	application context in the Host's application base directory.</li>
		282	<li><strong>webapp.war</strong> - The name of a web application war file
		283	located in the Host's application base directory.</li>
		284	</ul></li>
		285	</ul>
		286
		287	<p>Each command will return a response in <code>text/plain</code> format
		288	(i.e. plain ASCII with no HTML markup), making it easy for both humans and
		289	programs to read). The first line of the response will begin with either
		290	<code>OK</code> or <code>FAIL</code>, indicating whether the requested
		291	command was successful or not. In the case of failure, the rest of the first
		292	line will contain a description of the problem that was encountered. Some
		293	commands include additional lines of information as described below.</p>
		294
		295	<p><em>Internationalization Note</em> - The Manager application looks up
		296	its message strings in resource bundles, so it is possible that the strings
		297	have been translated for your platform. The examples below show the English
		298	version of the messages.</p>
		299
		300	</div></div>
		301
		302	<div class="subsection"><h4 id="Deploy_A_New_Application_Archive_(WAR)_Remotely">Deploy A New Application Archive (WAR) Remotely</h4><div class="text">
		303
		304	<div class="codeBox"><pre><code>http://localhost:8080/manager/text/deploy?path=/foo</code></pre></div>
		305
		306	<p>Upload the web application archive (WAR) file that is specified as the
		307	request data in this HTTP PUT request, install it into the <code>appBase</code>
		308	directory of our corresponding virtual host, and start, deriving the name for
		309	the WAR file added to the <code>appBase</code> from the specified path. The
		310	application can later be undeployed (and the corresponding WAR file removed) by
		311	use of the <code>/undeploy</code> command.</p>
		312
		313	<p>This command is executed by an HTTP PUT request.</p>
		314
		315	<p>The .WAR file may include Tomcat specific deployment configuration, by
		316	including a Context configuration XML file in
		317	<code>/META-INF/context.xml</code>.</p>
		318
		319	<p>URL parameters include:</p>
		320	<ul>
		321	<li><code>update</code>: When set to true, any existing update will be
		322	undeployed first. The default value is set to false.</li>
		323	<li><code>tag</code>: Specifying a tag name, this allows associating the
		324	deployed webapp with a tag or label. If the web application is undeployed,
		325	it can be later redeployed when needed using only the tag.</li>
		326	<li><code>config </code>: URL of a Context configuration ".xml" file in the
		327	format <strong>file:/absolute/path/to/a/context.xml</strong>. This must be
		328	the absolute path of a web application Context configuration ".xml" file
		329	which contains the Context configuration element.</li>
		330	</ul>
		331
		332	<p><strong>NOTE</strong> - This command is the logical
		333	opposite of the <code>/undeploy</code> command.</p>
		334
		335	<p>If installation and startup is successful, you will receive a response
		336	like this:</p>
		337	<div class="codeBox"><pre><code>OK - Deployed application at context path /foo</code></pre></div>
		338
		339	<p>Otherwise, the response will start with <code>FAIL</code> and include an
		340	error message. Possible causes for problems include:</p>
		341	<ul>
		342	<li><em>Application already exists at path /foo</em>
		343	<p>The context paths for all currently running web applications must be
		344	unique. Therefore, you must undeploy the existing web
		345	application using this context path, or choose a different context path
		346	for the new one. The <code>update</code> parameter may be specified as
		347	a parameter on the URL, with a value of <code>true</code> to avoid this
		348	error. In that case, an undeploy will be performed on an existing
		349	application before performing the deployment.</p>
		350	</li>
		351	<li><em>Encountered exception</em>
		352	<p>An exception was encountered trying to start the new web application.
		353	Check the Tomcat logs for the details, but likely explanations include
		354	problems parsing your <code>/WEB-INF/web.xml</code> file, or missing
		355	classes encountered when initializing application event listeners and
		356	filters.</p>
		357	</li>
		358	</ul>
		359
		360	</div></div>
		361
		362	<div class="subsection"><h4 id="Deploy_A_New_Application_from_a_Local_Path">Deploy A New Application from a Local Path</h4><div class="text">
		363
		364	<p>Deploy and start a new web application, attached to the specified context
		365	<code>path</code> (which must not be in use by any other web application).
		366	This command is the logical opposite of the <code>/undeploy</code> command.</p>
		367
		368	<p>This command is executed by an HTTP GET request.
		369	There are a number of different ways the deploy command can be used.</p>
		370
		371	<div class="subsection"><h4 id="Deploy_a_previously_deployed_webapp">Deploy a previously deployed webapp</h4><div class="text">
		372
		373	<div class="codeBox"><pre><code>http://localhost:8080/manager/text/deploy?path=/footoo&tag=footag</code></pre></div>
		374
		375	<p>This can be used to deploy a previously deployed web application, which
		376	has been deployed using the <code>tag</code> attribute. Note that the work
		377	directory of the Manager webapp will contain the previously deployed WARs;
		378	removing it would make the deployment fail.</p>
		379
		380	</div></div>
		381
		382	<div class="subsection"><h4 id="Deploy_a_Directory_or_WAR_by_URL">Deploy a Directory or WAR by URL</h4><div class="text">
		383
		384	<p>Deploy a web application directory or ".war" file located on the Tomcat
		385	server. If no <code>path</code> is specified, the path and version are derived
		386	from the directory name or the war file name. The <code>war</code> parameter
		387	specifies a URL (including the <code>file:</code> scheme) for either
		388	a directory or a web application archive (WAR) file. The supported syntax for
		389	a URL referring to a WAR file is described on the Javadocs page for the
		390	<code>java.net.JarURLConnection</code> class. Use only URLs that refer to
		391	the entire WAR file.</p>
		392
		393	<p>In this example the web application located in the directory
		394	<code>/path/to/foo</code> on the Tomcat server is deployed as the
		395	web application context named <code>/footoo</code>.</p>
		396	<div class="codeBox"><pre><code>http://localhost:8080/manager/text/deploy?path=/footoo&war=file:/path/to/foo</code></pre></div>
		397
		398
		399	<p>In this example the ".war" file <code>/path/to/bar.war</code> on the
		400	Tomcat server is deployed as the web application context named
		401	<code>/bar</code>. Notice that there is no <code>path</code> parameter
		402	so the context path defaults to the name of the web application archive
		403	file without the ".war" extension.</p>
		404	<div class="codeBox"><pre><code>http://localhost:8080/manager/text/deploy?war=file:/path/to/bar.war</code></pre></div>
		405
		406	</div></div>
		407
		408	<div class="subsection"><h4 id="Deploy_a_Directory_or_War_from_the_Host_appBase">Deploy a Directory or War from the Host appBase</h4><div class="text">
		409
		410	<p>Deploy a web application directory or ".war" file located in your Host
		411	appBase directory. The path and optional version are derived from the directory
		412	or war file name.</p>
		413
		414	<p>In this example the web application located in a sub directory named
		415	<code>foo</code> in the Host appBase directory of the Tomcat server is
		416	deployed as the web application context named <code>/foo</code>. Notice
		417	that the context path used is the name of the web application directory.</p>
		418	<div class="codeBox"><pre><code>http://localhost:8080/manager/text/deploy?war=foo</code></pre></div>
		419
		420
		421	<p>In this example the ".war" file <code>bar.war</code> located in your
		422	Host appBase directory on the Tomcat server is deployed as the web
		423	application context named <code>/bar</code>.</p>
		424	<div class="codeBox"><pre><code>http://localhost:8080/manager/text/deploy?war=bar.war</code></pre></div>
		425
		426	</div></div>
		427
		428	<div class="subsection"><h4 id="Deploy_using_a_Context_configuration_".xml"_file">Deploy using a Context configuration ".xml" file</h4><div class="text">
		429
		430	<p>If the Host deployXML flag is set to true you can deploy a web
		431	application using a Context configuration ".xml" file and an optional
		432	".war" file or web application directory. The context <code>path</code>
		433	is not used when deploying a web application using a context ".xml"
		434	configuration file.</p>
		435
		436	<p>A Context configuration ".xml" file can contain valid XML for a
		437	web application Context just as if it were configured in your
		438	Tomcat <code>server.xml</code> configuration file. Here is an
		439	example:</p>
		440	<div class="codeBox"><pre><code><Context path="/foobar" docBase="/path/to/application/foobar">
		441	</Context></code></pre></div>
		442
		443
		444	<p>When the optional <code>war</code> parameter is set to the URL
		445	for a web application ".war" file or directory it overrides any
		446	docBase configured in the context configuration ".xml" file.</p>
		447
		448	<p>Here is an example of deploying an application using a Context
		449	configuration ".xml" file.</p>
		450	<div class="codeBox"><pre><code>http://localhost:8080/manager/text/deploy?config=file:/path/context.xml</code></pre></div>
		451
		452
		453	<p>Here is an example of deploying an application using a Context
		454	configuration ".xml" file and a web application ".war" file located
		455	on the server.</p>
		456	<div class="codeBox"><pre><code>http://localhost:8080/manager/text/deploy
		457	?config=file:/path/context.xml&war=file:/path/bar.war</code></pre></div>
		458
		459	</div></div>
		460
		461	<div class="subsection"><h4 id="Deployment_Notes">Deployment Notes</h4><div class="text">
		462
		463	<p>If the Host is configured with unpackWARs=true and you deploy a war
		464	file, the war will be unpacked into a directory in your Host appBase
		465	directory.</p>
		466
		467	<p>If the application war or directory is installed in your Host appBase
		468	directory and either the Host is configured with autoDeploy=true or the
		469	Context path must match the directory name or war file name without the
		470	".war" extension.</p>
		471
		472	<p>For security when untrusted users can manage web applications, the
		473	Host deployXML flag can be set to false. This prevents untrusted users
		474	from deploying web applications using a configuration XML file and
		475	also prevents them from deploying application directories or ".war"
		476	files located outside of their Host appBase.</p>
		477
		478	</div></div>
		479
		480	<div class="subsection"><h4 id="Deploy_Response">Deploy Response</h4><div class="text">
		481
		482	<p>If installation and startup is successful, you will receive a response
		483	like this:</p>
		484	<div class="codeBox"><pre><code>OK - Deployed application at context path /foo</code></pre></div>
		485
		486	<p>Otherwise, the response will start with <code>FAIL</code> and include an
		487	error message. Possible causes for problems include:</p>
		488	<ul>
		489	<li><em>Application already exists at path /foo</em>
		490	<p>The context paths for all currently running web applications must be
		491	unique. Therefore, you must undeploy the existing web
		492	application using this context path, or choose a different context path
		493	for the new one. The <code>update</code> parameter may be specified as
		494	a parameter on the URL, with a value of <code>true</code> to avoid this
		495	error. In that case, an undeploy will be performed on an existing
		496	application before performing the deployment.</p>
		497	</li>
		498	<li><em>Document base does not exist or is not a readable directory</em>
		499	<p>The URL specified by the <code>war</code> parameter must identify a
		500	directory on this server that contains the "unpacked" version of a
		501	web application, or the absolute URL of a web application archive (WAR)
		502	file that contains this application. Correct the value specified by
		503	the <code>war</code> parameter.</p>
		504	</li>
		505	<li><em>Encountered exception</em>
		506	<p>An exception was encountered trying to start the new web application.
		507	Check the Tomcat logs for the details, but likely explanations include
		508	problems parsing your <code>/WEB-INF/web.xml</code> file, or missing
		509	classes encountered when initializing application event listeners and
		510	filters.</p>
		511	</li>
		512	<li><em>Invalid application URL was specified</em>
		513	<p>The URL for the directory or web application that you specified
		514	was not valid. Such URLs must start with <code>file:</code>, and URLs
		515	for a WAR file must end in ".war".</p>
		516	</li>
		517	<li><em>Invalid context path was specified</em>
		518	<p>The context path must start with a slash character. To reference the
		519	ROOT web application use "/".</p>
		520	</li>
		521	<li><em>Context path must match the directory or WAR file name:</em>
		522	<p>If the application war or directory is installed in your Host appBase
		523	directory and either the Host is configured with autoDeploy=true the
		524	Context path must match the directory name or war file name without
		525	the ".war" extension.</p>
		526	</li>
		527	<li><em>Only web applications in the Host web application directory can
		528	be installed</em>
		529	<p>
		530	If the Host deployXML flag is set to false this error will happen
		531	if an attempt is made to deploy a web application directory or
		532	".war" file outside of the Host appBase directory.
		533	</p></li>
		534	</ul>
		535
		536	</div></div>
		537	</div></div>
		538
		539	<div class="subsection"><h4 id="List_Currently_Deployed_Applications">List Currently Deployed Applications</h4><div class="text">
		540
		541	<div class="codeBox"><pre><code>http://localhost:8080/manager/text/list</code></pre></div>
		542
		543	<p>List the context paths, current status (<code>running</code> or
		544	<code>stopped</code>), and number of active sessions for all currently
		545	deployed web applications. A typical response immediately
		546	after starting Tomcat might look like this:</p>
		547	<div class="codeBox"><pre><code>OK - Listed applications for virtual host localhost
		548	/webdav:running:0:webdav
		549	/examples:running:0:examples
		550	/manager:running:0:manager
		551	/:running:0:ROOT
		552	/test:running:0:test##2
		553	/test:running:0:test##1</code></pre></div>
		554
		555	</div></div>
		556
		557	<div class="subsection"><h4 id="Reload_An_Existing_Application">Reload An Existing Application</h4><div class="text">
		558
		559	<div class="codeBox"><pre><code>http://localhost:8080/manager/text/reload?path=/examples</code></pre></div>
		560
		561	<p>Signal an existing application to shut itself down and reload. This can
		562	be useful when the web application context is not reloadable and you have
		563	updated classes or property files in the <code>/WEB-INF/classes</code>
		564	directory or when you have added or updated jar files in the
		565	<code>/WEB-INF/lib</code> directory.
		566	</p>
		567
		568	<p>If this command succeeds, you will see a response like this:</p>
		569	<div class="codeBox"><pre><code>OK - Reloaded application at context path /examples</code></pre></div>
		570
		571	<p>Otherwise, the response will start with <code>FAIL</code> and include an
		572	error message. Possible causes for problems include:</p>
		573	<ul>
		574	<li><em>Encountered exception</em>
		575	<p>An exception was encountered trying to restart the web application.
		576	Check the Tomcat logs for the details.</p>
		577	</li>
		578	<li><em>Invalid context path was specified</em>
		579	<p>The context path must start with a slash character. To reference the
		580	ROOT web application use "/".</p>
		581	</li>
		582	<li><em>No context exists for path /foo</em>
		583	<p>There is no deployed application on the context path
		584	that you specified.</p>
		585	</li>
		586	<li><em>No context path was specified</em>
		587	<p>
		588	The <code>path</code> parameter is required.
		589	</p></li>
		590	<li><em>Reload not supported on WAR deployed at path /foo</em>
		591	<p>
		592	Currently, application reloading (to pick up changes to the classes or
		593	<code>web.xml</code> file) is not supported when a web application is
		594	deployed directly from a WAR file. It only works when the web application
		595	is deployed from an unpacked directory. If you are using a WAR file,
		596	you should <code>undeploy</code> and then <code>deploy</code> or
		597	<code>deploy</code> with the <code>update</code> parameter the
		598	application again to pick up your changes.
		599	</p></li>
		600	</ul>
		601
		602	</div></div>
		603
		604	<div class="subsection"><h4 id="List_OS_and_JVM_Properties">List OS and JVM Properties</h4><div class="text">
		605
		606	<div class="codeBox"><pre><code>http://localhost:8080/manager/text/serverinfo</code></pre></div>
		607
		608	<p>Lists information about the Tomcat version, OS, and JVM properties.</p>
		609
		610	<p>If an error occurs, the response will start with <code>FAIL</code> and
		611	include an error message. Possible causes for problems include:</p>
		612	<ul>
		613	<li><em>Encountered exception</em>
		614	<p>An exception was encountered trying to enumerate the system properties.
		615	Check the Tomcat logs for the details.</p>
		616	</li>
		617	</ul>
		618
		619	</div></div>
		620
		621	<div class="subsection"><h4 id="List_Available_Global_JNDI_Resources">List Available Global JNDI Resources</h4><div class="text">
		622
		623	<div class="codeBox"><pre><code>http://localhost:8080/manager/text/resources[?type=xxxxx]</code></pre></div>
		624
		625	<p>List the global JNDI resources that are available for use in resource
		626	links for context configuration files. If you specify the <code>type</code>
		627	request parameter, the value must be the fully qualified Java class name of
		628	the resource type you are interested in (for example, you would specify
		629	<code>javax.sql.DataSource</code> to acquire the names of all available
		630	JDBC data sources). If you do not specify the <code>type</code> request
		631	parameter, resources of all types will be returned.</p>
		632
		633	<p>Depending on whether the <code>type</code> request parameter is specified
		634	or not, the first line of a normal response will be:</p>
		635	<div class="codeBox"><pre><code>OK - Listed global resources of all types</code></pre></div>
		636	<p>or</p>
		637	<div class="codeBox"><pre><code>OK - Listed global resources of type xxxxx</code></pre></div>
		638	<p>followed by one line for each resource. Each line is composed of fields
		639	delimited by colon characters (":"), as follows:</p>
		640	<ul>
		641	<li><em>Global Resource Name</em> - The name of this global JNDI resource,
		642	which would be used in the <code>global</code> attribute of a
		643	<code><ResourceLink></code> element.</li>
		644	<li><em>Global Resource Type</em> - The fully qualified Java class name of
		645	this global JNDI resource.</li>
		646	</ul>
		647
		648	<p>If an error occurs, the response will start with <code>FAIL</code> and
		649	include an error message. Possible causes for problems include:</p>
		650	<ul>
		651	<li><em>Encountered exception</em>
		652	<p>An exception was encountered trying to enumerate the global JNDI
		653	resources. Check the Tomcat logs for the details.</p>
		654	</li>
		655	<li><em>No global JNDI resources are available</em>
		656	<p>The Tomcat server you are running has been configured without
		657	global JNDI resources.</p>
		658	</li>
		659	</ul>
		660
		661
		662	</div></div>
		663
		664	<div class="subsection"><h4 id="Session_Statistics">Session Statistics</h4><div class="text">
		665
		666	<div class="codeBox"><pre><code>http://localhost:8080/manager/text/sessions?path=/examples</code></pre></div>
		667
		668	<p>Display the default session timeout for a web application, and the
		669	number of currently active sessions that fall within one-minute ranges of
		670	their actual timeout times. For example, after restarting Tomcat and then
		671	executing one of the JSP samples in the <code>/examples</code> web app,
		672	you might get something like this:</p>
		673
		674	<div class="codeBox"><pre><code>OK - Session information for application at context path /examples
		675	Default maximum session inactive interval 30 minutes
		676	<1 minutes: 1 sessions
		677	1 - <2 minutes: 1 sessions</code></pre></div>
		678
		679	</div></div>
		680
		681	<div class="subsection"><h4 id="Expire_Sessions">Expire Sessions</h4><div class="text">
		682
		683	<div class="codeBox"><pre><code>http://localhost:8080/manager/text/expire?path=/examples&idle=num</code></pre></div>
		684
		685	<p>Display the session statistics (like the above <code>/sessions</code>
		686	command) and expire sessions that are idle for longer than <code>num</code>
		687	minutes. To expire all sessions, use <code>&idle=0</code> .</p>
		688
		689	<div class="codeBox"><pre><code>OK - Session information for application at context path /examples
		690	Default maximum session inactive interval 30 minutes
		691	1 - <2 minutes: 1 sessions
		692	3 - <4 minutes: 1 sessions
		693	>0 minutes: 2 sessions were expired</code></pre></div>
		694
		695	<p>Actually <code>/sessions</code> and <code>/expire</code> are synonyms for
		696	the same command. The difference is in the presence of <code>idle</code>
		697	parameter.</p>
		698
		699	</div></div>
		700
		701	<div class="subsection"><h4 id="Start_an_Existing_Application">Start an Existing Application</h4><div class="text">
		702
		703	<div class="codeBox"><pre><code>http://localhost:8080/manager/text/start?path=/examples</code></pre></div>
		704
		705	<p>Signal a stopped application to restart, and make itself available again.
		706	Stopping and starting is useful, for example, if the database required by
		707	your application becomes temporarily unavailable. It is usually better to
		708	stop the web application that relies on this database rather than letting
		709	users continuously encounter database exceptions.</p>
		710
		711	<p>If this command succeeds, you will see a response like this:</p>
		712	<div class="codeBox"><pre><code>OK - Started application at context path /examples</code></pre></div>
		713
		714	<p>Otherwise, the response will start with <code>FAIL</code> and include an
		715	error message. Possible causes for problems include:</p>
		716	<ul>
		717	<li><em>Encountered exception</em>
		718	<p>An exception was encountered trying to start the web application.
		719	Check the Tomcat logs for the details.</p>
		720	</li>
		721	<li><em>Invalid context path was specified</em>
		722	<p>The context path must start with a slash character. To reference the
		723	ROOT web application use "/".</p>
		724	</li>
		725	<li><em>No context exists for path /foo</em>
		726	<p>There is no deployed application on the context path
		727	that you specified.</p>
		728	</li>
		729	<li><em>No context path was specified</em>
		730	<p>
		731	The <code>path</code> parameter is required.
		732	</p></li>
		733	</ul>
		734
		735	</div></div>
		736
		737	<div class="subsection"><h4 id="Stop_an_Existing_Application">Stop an Existing Application</h4><div class="text">
		738
		739	<div class="codeBox"><pre><code>http://localhost:8080/manager/text/stop?path=/examples</code></pre></div>
		740
		741	<p>Signal an existing application to make itself unavailable, but leave it
		742	deployed. Any request that comes in while an application is
		743	stopped will see an HTTP error 404, and this application will show as
		744	"stopped" on a list applications command.</p>
		745
		746	<p>If this command succeeds, you will see a response like this:</p>
		747	<div class="codeBox"><pre><code>OK - Stopped application at context path /examples</code></pre></div>
		748
		749	<p>Otherwise, the response will start with <code>FAIL</code> and include an
		750	error message. Possible causes for problems include:</p>
		751	<ul>
		752	<li><em>Encountered exception</em>
		753	<p>An exception was encountered trying to stop the web application.
		754	Check the Tomcat logs for the details.</p>
		755	</li>
		756	<li><em>Invalid context path was specified</em>
		757	<p>The context path must start with a slash character. To reference the
		758	ROOT web application use "/".</p>
		759	</li>
		760	<li><em>No context exists for path /foo</em>
		761	<p>There is no deployed application on the context path
		762	that you specified.</p>
		763	</li>
		764	<li><em>No context path was specified</em>
		765	The <code>path</code> parameter is required.
		766	</li>
		767	</ul>
		768
		769	</div></div>
		770
		771
		772	<div class="subsection"><h4 id="Undeploy_an_Existing_Application">Undeploy an Existing Application</h4><div class="text">
		773
		774	<div class="codeBox"><pre><code>http://localhost:8080/manager/text/undeploy?path=/examples</code></pre></div>
		775
		776	<p><strong><span style="color: red;">WARNING</span> - This command will delete any web
		777	application artifacts that exist within <code>appBase</code> directory
		778	(typically "webapps") for this virtual host</strong>.
		779	This will delete the application .WAR, if present,
		780	the application directory resulting either from a deploy in unpacked form
		781	or from .WAR expansion as well as the XML Context definition from
		782	<code>$CATALINA_BASE/conf/[enginename]/[hostname]/</code> directory.
		783	If you simply want to take an application
		784	out of service, you should use the <code>/stop</code> command instead.</p>
		785
		786	<p>Signal an existing application to gracefully shut itself down, and
		787	remove it from Tomcat (which also makes this context path available for
		788	reuse later). In addition, the document root directory is removed, if it
		789	exists in the <code>appBase</code> directory (typically "webapps") for
		790	this virtual host. This command is the logical opposite of the
		791	<code>/deploy</code> command.</p>
		792
		793	<p>If this command succeeds, you will see a response like this:</p>
		794	<div class="codeBox"><pre><code>OK - Undeployed application at context path /examples</code></pre></div>
		795
		796	<p>Otherwise, the response will start with <code>FAIL</code> and include an
		797	error message. Possible causes for problems include:</p>
		798	<ul>
		799	<li><em>Encountered exception</em>
		800	<p>An exception was encountered trying to undeploy the web application.
		801	Check the Tomcat logs for the details.</p>
		802	</li>
		803	<li><em>Invalid context path was specified</em>
		804	<p>The context path must start with a slash character. To reference the
		805	ROOT web application use "/".</p>
		806	</li>
		807	<li><em>No context exists named /foo</em>
		808	<p>There is no deployed application with the name that you specified.</p>
		809	</li>
		810	<li><em>No context path was specified</em>
		811	The <code>path</code> parameter is required.
		812	</li>
		813	</ul>
		814
		815	</div></div>
		816
		817	<div class="subsection"><h4 id="Finding_memory_leaks">Finding memory leaks</h4><div class="text">
		818
		819	<div class="codeBox"><pre><code>http://localhost:8080/manager/text/findleaks[?statusLine=[true\|false]]</code></pre></div>
		820
		821	<p><strong>The find leaks diagnostic triggers a full garbage collection. It
		822	should be used with extreme caution on production systems.</strong></p>
		823
		824	<p>The find leaks diagnostic attempts to identify web applications that have
		825	caused memory leaks when they were stopped, reloaded or undeployed. Results
		826	should always be confirmed
		827	with a profiler. The diagnostic uses additional functionality provided by the
		828	StandardHost implementation. It will not work if a custom host is used that
		829	does not extend StandardHost.</p>
		830
		831	<p>Explicitly triggering a full garbage collection from Java code is documented
		832	to be unreliable. Furthermore, depending on the JVM used, there are options to
		833	disable explicit GC triggering, like <code>-XX:+DisableExplicitGC</code>.
		834	If you want to make sure, that the diagnostics were successfully running a full
		835	GC, you will need to check using tools like GC logging, JConsole or similar.</p>
		836
		837	<p>If this command succeeds, you will see a response like this:</p>
		838	<div class="codeBox"><pre><code>/leaking-webapp</code></pre></div>
		839
		840	<p>If you wish to see a status line included in the response then include the
		841	<code>statusLine</code> query parameter in the request with a value of
		842	<code>true</code>.</p>
		843
		844	<p>Each context path for a web application that was stopped, reloaded or
		845	undeployed, but which classes from the previous runs are still loaded in memory,
		846	thus causing a memory leak, will be listed on a new line. If an application
		847	has been reloaded several times, it may be listed several times.</p>
		848
		849	<p>If the command does not succeed, the response will start with
		850	<code>FAIL</code> and include an error message.</p>
		851
		852	</div></div>
		853
		854	<div class="subsection"><h4 id="Connector_SSL/TLS_cipher_information">Connector SSL/TLS cipher information</h4><div class="text">
		855
		856	<div class="codeBox"><pre><code>http://localhost:8080/manager/text/sslConnectorCiphers</code></pre></div>
		857
		858	<p>The SSL Connector/Ciphers diagnostic lists the SSL/TLS ciphers that are currently
		859	configured for each connector. For NIO and NIO2, the names of the individual
		860	cipher suites are listed. For APR, the value of SSLCipherSuite is returned.</p>
		861
		862	<p>The response will look something like this:</p>
		863	<div class="codeBox"><pre><code>OK - Connector / SSL Cipher information
		864	Connector[HTTP/1.1-8080]
		865	SSL is not enabled for this connector
		866	Connector[HTTP/1.1-8443]
		867	TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA
		868	TLS_DHE_RSA_WITH_AES_128_CBC_SHA
		869	TLS_ECDH_RSA_WITH_AES_128_CBC_SHA
		870	TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA
		871	...</code></pre></div>
		872
		873	</div></div>
		874
		875	<div class="subsection"><h4 id="Connector_SSL/TLS_certificate_chain_information">Connector SSL/TLS certificate chain information</h4><div class="text">
		876
		877	<div class="codeBox"><pre><code>http://localhost:8080/manager/text/sslConnectorCerts</code></pre></div>
		878
		879	<p>The SSL Connector/Certs diagnostic lists the certificate chain that is
		880	currently configured for each virtual host.</p>
		881
		882	<p>The response will look something like this:</p>
		883	<div class="codeBox"><pre><code>OK - Connector / Certificate Chain information
		884	Connector[HTTP/1.1-8080]
		885	SSL is not enabled for this connector
		886	Connector[HTTP/1.1-8443]-_default_-RSA
		887	[
		888	[
		889	Version: V3
		890	Subject: CN=localhost, OU=Apache Tomcat PMC, O=The Apache Software Foundation, L=Wakefield, ST=MA, C=US
		891	Signature Algorithm: SHA256withRSA, OID = 1.2.840.113549.1.1.11
		892	...</code></pre></div>
		893
		894	</div></div>
		895
		896	<div class="subsection"><h4 id="Connector_SSL/TLS_trusted_certificate_information">Connector SSL/TLS trusted certificate information</h4><div class="text">
		897
		898	<div class="codeBox"><pre><code>http://localhost:8080/manager/text/sslConnectorTrustedCerts</code></pre></div>
		899
		900	<p>The SSL Connector/Certs diagnostic lists the trusted certificates that are
		901	currently configured for each virtual host.</p>
		902
		903	<p>The response will look something like this:</p>
		904	<div class="codeBox"><pre><code>OK - Connector / Trusted Certificate information
		905	Connector[HTTP/1.1-8080]
		906	SSL is not enabled for this connector
		907	Connector[HTTP/1.1-8443]-_default_
		908	[
		909	[
		910	Version: V3
		911	Subject: CN=Apache Tomcat Test CA, OU=Apache Tomcat PMC, O=The Apache Software Foundation, L=Wakefield, ST=MA, C=US
		912	...</code></pre></div>
		913
		914	</div></div>
		915
		916	<div class="subsection"><h4 id="Reload_TLS_configuration">Reload TLS configuration</h4><div class="text">
		917
		918	<div class="codeBox"><pre><code>http://localhost:8080/manager/text/sslReload?tlsHostName=name</code></pre></div>
		919
		920	<p>Reload the TLS configuration files (the certificate and key files, this does
		921	not trigger a re-parsing of server.xml). To reload the files for all hosts don't
		922	specify the <code>tlsHostName</code> parameter.</p>
		923
		924	<div class="codeBox"><pre><code>OK - Reloaded TLS configuration for [_default_]</code></pre></div>
		925
		926	</div></div>
		927
		928	<div class="subsection"><h4 id="Thread_Dump">Thread Dump</h4><div class="text">
		929
		930	<div class="codeBox"><pre><code>http://localhost:8080/manager/text/threaddump</code></pre></div>
		931
		932	<p>Write a JVM thread dump.</p>
		933
		934	<p>The response will look something like this:</p>
		935	<div class="codeBox"><pre><code>OK - JVM thread dump
		936	2014-12-08 07:24:40.080
		937	Full thread dump Java HotSpot(TM) Client VM (25.25-b02 mixed mode):
		938
		939	"http-nio-8080-exec-2" Id=26 cpu=46800300 ns usr=46800300 ns blocked 0 for -1 ms waited 0 for -1 ms
		940	java.lang.Thread.State: RUNNABLE
		941	locks java.util.concurrent.ThreadPoolExecutor$Worker@1738ad4
		942	at sun.management.ThreadImpl.dumpThreads0(Native Method)
		943	at sun.management.ThreadImpl.dumpAllThreads(ThreadImpl.java:446)
		944	at org.apache.tomcat.util.Diagnostics.getThreadDump(Diagnostics.java:440)
		945	at org.apache.tomcat.util.Diagnostics.getThreadDump(Diagnostics.java:409)
		946	at org.apache.catalina.manager.ManagerServlet.threadDump(ManagerServlet.java:557)
		947	at org.apache.catalina.manager.ManagerServlet.doGet(ManagerServlet.java:371)
		948	at javax.servlet.http.HttpServlet.service(HttpServlet.java:618)
		949	at javax.servlet.http.HttpServlet.service(HttpServlet.java:725)
		950	...
		951	</code></pre></div>
		952
		953	</div></div>
		954
		955	<div class="subsection"><h4 id="VM_Info">VM Info</h4><div class="text">
		956
		957	<div class="codeBox"><pre><code>http://localhost:8080/manager/text/vminfo</code></pre></div>
		958
		959	<p>Write some diagnostic information about Java Virtual Machine.</p>
		960
		961	<p>The response will look something like this:</p>
		962	<div class="codeBox"><pre><code>OK - VM info
		963	2014-12-08 07:27:32.578
		964	Runtime information:
		965	vmName: Java HotSpot(TM) Client VM
		966	vmVersion: 25.25-b02
		967	vmVendor: Oracle Corporation
		968	specName: Java Virtual Machine Specification
		969	specVersion: 1.8
		970	specVendor: Oracle Corporation
		971	managementSpecVersion: 1.2
		972	name: ...
		973	startTime: 1418012458849
		974	uptime: 393855
		975	isBootClassPathSupported: true
		976
		977	OS information:
		978	...
		979	</code></pre></div>
		980
		981	</div></div>
		982
		983	<div class="subsection"><h4 id="Save_Configuration">Save Configuration</h4><div class="text">
		984
		985	<div class="codeBox"><pre><code>http://localhost:8080/manager/text/save</code></pre></div>
		986
		987	<p>If specified without any parameters, this command saves the current
		988	configuration of the server to server.xml. The existing file will be renamed as
		989	a backup if required.</p>
		990
		991	<p>If specified with a <code>path</code> parameter that matches the path of
		992	a deployed web application then the configuration for that web application will
		993	be saved to an appropriately named context.xml file in the <code>xmlBase</code>
		994	for the current Host.</p>
		995
		996	<p>To use the command a StoreConfig MBean must be present. Typically this is
		997	configured using the <a href="config/listeners.html#StoreConfig_Lifecycle_Listener_-_org.apache.catalina.storeconfig.StoreConfigLifecycleListener">StoreConfigLifecycleListener</a>.
		998	</p>
		999
		1000	<p>If the command does not succeed, the response will start with
		1001	<code>FAIL</code> and include an error message.</p>
		1002
		1003	</div></div>
		1004
		1005	</div><h3 id="Server_Status">Server Status</h3><div class="text">
		1006
		1007	<p>From the following links you can view Status information about the server.
		1008	The <code>manager-status</code> role or any one of the other
		1009	<strong>manager-xxx</strong> roles allow access to this page.</p>
		1010
		1011	<div class="codeBox"><pre><code>http://localhost:8080/manager/status
		1012	http://localhost:8080/manager/status/all</code></pre></div>
		1013
		1014	<p>Displays server status information in HTML format.</p>
		1015
		1016	<div class="codeBox"><pre><code>http://localhost:8080/manager/status?XML=true</code></pre></div>
		1017
		1018	<p>Displays server status information in XML format. The XML format does
		1019	not include the detailed per web application statistics.</p>
		1020
		1021	<div class="codeBox"><pre><code>http://localhost:8080/manager/status?JSON=true
		1022	http://localhost:8080/manager/status/all?JSON=true</code></pre></div>
		1023
		1024	<p>Displays server status information in JSON format. The JSON format does
		1025	not include the per thread state information. If using a client visualization
		1026	tool for active monitoring and server status alerts (such as Grafana), the JSON
		1027	output provided by the Manager will likely provide the easiest and most secure
		1028	solution.</p>
		1029
		1030	<p>First, you have the server and JVM version number, JVM provider, OS name
		1031	and number followed by the architecture type.</p>
		1032
		1033	<p>Second, there is information about the memory usage of the JVM.</p>
		1034
		1035	<p>Then, there is information about the Tomcat AJP and HTTP connectors.
		1036	The same information is available for both of them :
		1037	</p>
		1038	<ul>
		1039	<li><p>Threads information : Max threads, min and max spare threads,
		1040	current thread count and current thread busy.</p></li>
		1041	<li><p>Request information : Max processing time and processing time,
		1042	request and error count, bytes received and sent.</p></li>
		1043	<li><p>If not using the JSON format, the state of threads with Stage,
		1044	Time, Bytes Sent, Bytes Receive, Client, VHost and Request.
		1045	All existing threads are listed in the table.
		1046	Here is the list of the possible thread stages :</p>
		1047	<ul>
		1048	<li><p><em>"Parse and Prepare Request"</em> : The request headers are
		1049	being parsed or the necessary preparation to read the request body (if
		1050	a transfer encoding has been specified) is taking place.</p></li>
		1051	<li><p><em>"Service"</em> : The thread is processing a request and
		1052	generating the response. This stage follows the "Parse and Prepare
		1053	Request" stage and precedes the "Finishing" stage. There is always at
		1054	least one thread in this stage (the server-status page).</p></li>
		1055	<li><p><em>"Finishing"</em> : The end of the request processing. Any
		1056	remainder of the response still in the output buffers is sent to the
		1057	client. This stage is followed by "Keep-Alive" if it is appropriate to
		1058	keep the connection alive or "Ready" if "Keep-Alive" is not
		1059	appropriate.</p></li>
		1060	<li><p><em>"Keep-Alive"</em> : The thread keeps the connection open to
		1061	the client in case the client sends another request. If another request
		1062	is received, the next stage will be "Parse and Prepare Request". If no
		1063	request is received before the keep alive times out, the connection will
		1064	be closed and the next stage will be "Ready".</p></li>
		1065	<li><p><em>"Ready"</em> : The thread is at rest and ready to be
		1066	used.</p></li>
		1067	</ul>
		1068	</li>
		1069	</ul>
		1070
		1071	<p>If you are using <code>/status/all</code> command, additional information
		1072	on each of deployed web applications will be available, except for the XML
		1073	format.</p>
		1074
		1075	</div><h3 id="Using_the_JMX_Proxy_Servlet">Using the JMX Proxy Servlet</h3><div class="text">
		1076
		1077	<div class="subsection"><h4 id="What_is_JMX_Proxy_Servlet">What is JMX Proxy Servlet</h4><div class="text">
		1078	The JMX Proxy Servlet is a lightweight proxy to get and set the
		1079	tomcat internals. (Or any class that has been exposed via an MBean)
		1080	Its usage is not very user friendly but the UI is
		1081	extremely helpful for integrating command line scripts for monitoring
		1082	and changing the internals of tomcat. You can do two things with the proxy:
		1083	get information and set information. For you to really understand the
		1084	JMX Proxy Servlet, you should have a general understanding of JMX.
		1085	If you don't know what JMX is, then prepare to be confused.
		1086	</div></div>
		1087
		1088	<div class="subsection"><h4 id="JMX_Query_command">JMX Query command</h4><div class="text">
		1089	<p>This takes the form:</p>
		1090	<div class="codeBox"><pre><code>http://webserver/manager/jmxproxy/?qry=STUFF</code></pre></div>
		1091	<p>Where <code>STUFF</code> is the JMX query you wish to perform. For example,
		1092	here are some queries you might wish to run:</p>
		1093	<ul>
		1094	<li>
		1095	<code>qry=%3Atype%3DRequestProcessor%2C -->
		1096	type=RequestProcessor</code> which will locate all
		1097	workers which can process requests and report
		1098	their state.
		1099	</li>
		1100	<li>
		1101	<code>qry=%3Aj2eeType=Servlet%2c -->
		1102	j2eeType=Servlet</code> which return all loaded servlets.
		1103	</li>
		1104	<li>
		1105	<code>qry=Catalina%3Atype%3DEnvironment%2Cresourcetype%3DGlobal%2Cname%3DsimpleValue -->
		1106	Catalina:type=Environment,resourcetype=Global,name=simpleValue</code>
		1107	which look for a specific MBean by the given name.
		1108	</li>
		1109	</ul>
		1110	<p>
		1111	You'll need to experiment with this to really understand its capabilities
		1112	If you provide no <code>qry</code> parameter, then all of the MBeans will
		1113	be displayed. We really recommend looking at the tomcat source code and
		1114	understand the JMX spec to get a better understanding of all the queries
		1115	you may run.
		1116	</p>
		1117	</div></div>
		1118
		1119	<div class="subsection"><h4 id="JMX_Get_command">JMX Get command</h4><div class="text">
		1120	<p>
		1121	The JXMProxyServlet also supports a "get" command that you can use to
		1122	fetch the value of a specific MBean's attribute. The general form of
		1123	the <code>get</code> command is:
		1124	</p>
		1125
		1126	<div class="codeBox"><pre><code>http://webserver/manager/jmxproxy/?get=BEANNAME&att=MYATTRIBUTE&key=MYKEY</code></pre></div>
		1127
		1128	<p>You must provide the following parameters:</p>
		1129	<ol>
		1130	<li><code>get</code>: The full bean name</li>
		1131	<li><code>att</code>: The attribute you wish to fetch</li>
		1132	<li><code>key</code>: (optional) The key into a CompositeData MBean attribute</li>
		1133	</ol>
		1134	<p>
		1135	If all goes well, then it will say OK, otherwise an error message will
		1136	be shown. For example, let's say we wish to fetch the current heap memory
		1137	data:
		1138	</p>
		1139
		1140	<div class="codeBox"><pre><code>http://webserver/manager/jmxproxy/?get=java.lang:type=Memory&att=HeapMemoryUsage</code></pre></div>
		1141
		1142	<p>Or, if you only want the "used" key:</p>
		1143
		1144	<div class="codeBox"><pre><code>http://webserver/manager/jmxproxy/
		1145	?get=java.lang:type=Memory&att=HeapMemoryUsage&key=used</code></pre></div>
		1146	</div></div>
		1147
		1148	<div class="subsection"><h4 id="JMX_Set_command">JMX Set command</h4><div class="text">
		1149	<p>
		1150	Now that you can query an MBean, its time to muck with Tomcat's internals!
		1151	The general form of the set command is :
		1152	</p>
		1153	<div class="codeBox"><pre><code>http://webserver/manager/jmxproxy/?set=BEANNAME&att=MYATTRIBUTE&val=NEWVALUE</code></pre></div>
		1154	<p>So you need to provide 3 request parameters:</p>
		1155	<ol>
		1156	<li><code>set</code>: The full bean name</li>
		1157	<li><code>att</code>: The attribute you wish to alter</li>
		1158	<li><code>val</code>: The new value </li>
		1159	</ol>
		1160	<p>
		1161	If all goes ok, then it will say OK, otherwise an error message will be
		1162	shown. For example, lets say we wish to turn up debugging on the fly for the
		1163	<code>ErrorReportValve</code>. The following will set debugging to 10.
		1164	</p>
		1165	<div class="codeBox"><pre><code>http://localhost:8080/manager/jmxproxy/
		1166	?set=Catalina%3Atype%3DValve%2Cname%3DErrorReportValve%2Chost%3Dlocalhost
		1167	&att=debug&val=10</code></pre></div>
		1168	<p>and my result is (YMMV):</p>
		1169	<div class="codeBox"><pre><code>Result: ok</code></pre></div>
		1170
		1171	<p>Here is what I see if I pass in a bad value. Here is the URL I used,
		1172	I try set debugging equal to 'cow':</p>
		1173	<div class="codeBox"><pre><code>http://localhost:8080/manager/jmxproxy/
		1174	?set=Catalina%3Atype%3DValve%2Cname%3DErrorReportValve%2Chost%3Dlocalhost
		1175	&att=debug&val=cow</code></pre></div>
		1176	<p>When I try that, my result is</p>
		1177	<div class="codeBox"><pre><code>Error: java.lang.NumberFormatException: For input string: "cow"</code></pre></div>
		1178	</div></div>
		1179
		1180	<div class="subsection"><h4 id="JMX_Invoke_command">JMX Invoke command</h4><div class="text">
		1181	<p>The <code>invoke</code> command enables methods to be called on MBeans. The
		1182	general form of the command is:</p>
		1183	<div class="codeBox"><pre><code>http://webserver/manager/jmxproxy/
		1184	?invoke=BEANNAME&op=METHODNAME&ps=COMMASEPARATEDPARAMETERS</code></pre></div>
		1185	<p>For example, to call the <code>findConnectors()</code> method of the
		1186	<strong>Service</strong> use:</p>
		1187	<div class="codeBox"><pre><code>http://localhost:8080/manager/jmxproxy/
		1188	?invoke=Catalina%3Atype%3DService&op=findConnectors&ps=</code></pre></div>
		1189	</div></div>
		1190	</div><h3 id="Executing_Manager_Commands_With_Ant">Executing Manager Commands With Ant</h3><div class="text">
		1191
		1192	<p>In addition to the ability to execute Manager commands via HTTP requests,
		1193	as documented above, Tomcat includes a convenient set of Task definitions
		1194	for the <em>Ant</em> (version 1.4 or later) build tool. In order to use these
		1195	commands, you must perform the following setup operations:</p>
		1196	<ul>
		1197	<li>Download the binary distribution of Ant from
		1198	<a href="https://ant.apache.org">https://ant.apache.org</a>.
		1199	You must use version <strong>1.4</strong> or later.</li>
		1200	<li>Install the Ant distribution in a convenient directory (called
		1201	ANT_HOME in the remainder of these instructions).</li>
		1202	<li>Add the <code>$ANT_HOME/bin</code> directory to your <code>PATH</code>
		1203	environment variable.</li>
		1204	<li>Configure at least one username/password combination in your Tomcat
		1205	user database that includes the <code>manager-script</code> role.</li>
		1206	</ul>
		1207
		1208	<p>To use custom tasks within Ant, you must declare them first with an
		1209	<code><import></code> element. Therefore, your <code>build.xml</code>
		1210	file might look something like this:</p>
		1211
		1212	<div class="codeBox"><pre><code><project name="My Application" default="compile" basedir=".">
		1213
		1214	<!-- Configure the directory into which the web application is built -->
		1215	<property name="build" value="${basedir}/build"/>
		1216
		1217	<!-- Configure the context path for this application -->
		1218	<property name="path" value="/myapp"/>
		1219
		1220	<!-- Configure properties to access the Manager application -->
		1221	<property name="url" value="http://localhost:8080/manager/text"/>
		1222	<property name="username" value="myusername"/>
		1223	<property name="password" value="mypassword"/>
		1224
		1225	<!-- Configure the path to the Tomcat installation -->
		1226	<property name="catalina.home" value="/usr/local/apache-tomcat"/>
		1227
		1228	<!-- Configure the custom Ant tasks for the Manager application -->
		1229	<import file="${catalina.home}/bin/catalina-tasks.xml"/>
		1230
		1231	<!-- Executable Targets -->
		1232	<target name="compile" description="Compile web application">
		1233	<!-- ... construct web application in ${build} subdirectory, and
		1234	generated a ${path}.war ... -->
		1235	</target>
		1236
		1237	<target name="deploy" description="Install web application"
		1238	depends="compile">
		1239	<deploy url="${url}" username="${username}" password="${password}"
		1240	path="${path}" war="file:${build}${path}.war"/>
		1241	</target>
		1242
		1243	<target name="reload" description="Reload web application"
		1244	depends="compile">
		1245	<reload url="${url}" username="${username}" password="${password}"
		1246	path="${path}"/>
		1247	</target>
		1248
		1249	<target name="undeploy" description="Remove web application">
		1250	<undeploy url="${url}" username="${username}" password="${password}"
		1251	path="${path}"/>
		1252	</target>
		1253
		1254	</project></code></pre></div>
		1255
		1256	<p>Note: The definition of the resources task via the import above will override
		1257	the resources datatype added in Ant 1.7. If you wish to use the resources
		1258	datatype you will need to use Ant's namespace support to modify
		1259	<code>catalina-tasks.xml</code> to assign the Tomcat tasks to their own
		1260	namespace.</p>
		1261
		1262	<p>Now, you can execute commands like <code>ant deploy</code> to deploy the
		1263	application to a running instance of Tomcat, or <code>ant reload</code> to
		1264	tell Tomcat to reload it. Note also that most of the interesting values in
		1265	this <code>build.xml</code> file are defined as replaceable properties, so
		1266	you can override their values from the command line. For example, you might
		1267	consider it a security risk to include the real manager password in your
		1268	<code>build.xml</code> file's source code. To avoid this, omit the password
		1269	property, and specify it from the command line:</p>
		1270	<div class="codeBox"><pre><code>ant -Dpassword=secret deploy</code></pre></div>
		1271
		1272	<div class="subsection"><h4 id="Tasks_output_capture">Tasks output capture</h4><div class="text">
		1273
		1274	<p>Using <em>Ant</em> version <strong>1.6.2</strong> or later,
		1275	the Catalina tasks offer the option to capture their output in
		1276	properties or external files. They support directly the following subset of the
		1277	<code><redirector></code> type attributes:
		1278	</p>
		1279
		1280	<table class="defaultTable">
		1281	<tr>
		1282	<th>Attribute</th>
		1283	<th>Description</th>
		1284	<th style="text-align: center;">Required</th>
		1285	</tr>
		1286	<tr>
		1287	<td>output</td>
		1288	<td>Name of a file to which to write the output. If
		1289	the error stream is not also redirected to a file or property, it will
		1290	appear in this output.</td>
		1291	<td style="text-align: center;">No</td>
		1292	</tr>
		1293	<tr>
		1294	<td>error</td>
		1295	<td>The file to which the standard error of the
		1296	command should be redirected.</td>
		1297	<td style="text-align: center;">No</td>
		1298	</tr>
		1299	<tr>
		1300	<td>logError</td>
		1301	<td>This attribute is used when you wish to see
		1302	error output in Ant's log and you are redirecting output to a
		1303	file/property. The error output will not be included in the output
		1304	file/property. If you redirect error with the <i>error</i> or <i>errorProperty</i>
		1305	attributes, this will have no effect.</td>
		1306	<td style="text-align: center;">No</td>
		1307	</tr>
		1308	<tr>
		1309	<td>append</td>
		1310	<td>Whether output and error files should be
		1311	appended to or overwritten. Defaults to <code>false</code>.</td>
		1312	<td style="text-align: center;">No</td>
		1313	</tr>
		1314	<tr>
		1315	<td>createemptyfiles</td>
		1316	<td>Whether output and error files should be created
		1317	even when empty. Defaults to <code>true</code>.</td>
		1318	<td style="text-align: center;">No</td>
		1319	</tr>
		1320	<tr>
		1321	<td>outputproperty</td>
		1322	<td>The name of a property in which the output of
		1323	the command should be stored. Unless the error stream is redirected to
		1324	a separate file or stream, this property will include the error output.</td>
		1325	<td style="text-align: center;">No</td>
		1326	</tr>
		1327	<tr>
		1328	<td>errorproperty</td>
		1329	<td>The name of a property in which the standard
		1330	error of the command should be stored.</td>
		1331	<td style="text-align: center;">No</td>
		1332	</tr>
		1333	</table>
		1334
		1335	<p>A couple of additional attributes can also be specified:
		1336	</p>
		1337	<table class="defaultTable">
		1338	<tr>
		1339	<th>Attribute</th>
		1340	<th>Description</th>
		1341	<th style="text-align: center;">Required</th>
		1342	</tr>
		1343	<tr>
		1344	<td>alwaysLog</td>
		1345	<td>This attribute is used when you wish to see the
		1346	output you are capturing, appearing also in the Ant's log. It must not be
		1347	used unless you are capturing task output.
		1348	Defaults to <code>false</code>.
		1349	<em>This attribute will be supported directly by <code><redirector></code>
		1350	in Ant 1.6.3</em></td>
		1351	<td style="text-align: center;">No</td>
		1352	</tr>
		1353	<tr>
		1354	<td>failonerror</td>
		1355	<td>This attribute is used when you wish to avoid that
		1356	any manager command processing error terminates the ant execution. Defaults to <code>true</code>.
		1357	It must be set to <code>false</code>, if you want to capture error output,
		1358	otherwise execution will terminate before anything can be captured.
		1359	<br>
		1360	This attribute acts only on manager command execution,
		1361	any wrong or missing command attribute will still cause Ant execution termination.
		1362	</td>
		1363	<td style="text-align: center;">No</td>
		1364	</tr>
		1365	</table>
		1366
		1367	<p>They also support the embedded <code><redirector></code> element
		1368	in which you can specify
		1369	its full set of attributes, but <code>input</code>, <code>inputstring</code> and
		1370	<code>inputencoding</code> that, even if accepted, are not used because they have
		1371	no meaning in this context.
		1372	Refer to <a href="https://ant.apache.org">ant manual</a> for details on
		1373	<code><redirector></code> element attributes.
		1374	</p>
		1375
		1376	<p>
		1377	Here is a sample build file extract that shows how this output redirection support
		1378	can be used:
		1379	</p>
		1380
		1381	<div class="codeBox"><pre><code> <target name="manager.deploy"
		1382	depends="context.status"
		1383	if="context.notInstalled">
		1384	<deploy url="${mgr.url}"
		1385	username="${mgr.username}"
		1386	password="${mgr.password}"
		1387	path="${mgr.context.path}"
		1388	config="${mgr.context.descriptor}"/>
		1389	</target>
		1390
		1391	<target name="manager.deploy.war"
		1392	depends="context.status"
		1393	if="context.deployable">
		1394	<deploy url="${mgr.url}"
		1395	username="${mgr.username}"
		1396	password="${mgr.password}"
		1397	update="${mgr.update}"
		1398	path="${mgr.context.path}"
		1399	war="${mgr.war.file}"/>
		1400	</target>
		1401
		1402	<target name="context.status">
		1403	<property name="running" value="${mgr.context.path}:running"/>
		1404	<property name="stopped" value="${mgr.context.path}:stopped"/>
		1405
		1406	<list url="${mgr.url}"
		1407	outputproperty="ctx.status"
		1408	username="${mgr.username}"
		1409	password="${mgr.password}">
		1410	</list>
		1411
		1412	<condition property="context.running">
		1413	<contains string="${ctx.status}" substring="${running}"/>
		1414	</condition>
		1415	<condition property="context.stopped">
		1416	<contains string="${ctx.status}" substring="${stopped}"/>
		1417	</condition>
		1418	<condition property="context.notInstalled">
		1419	<and>
		1420	<isfalse value="${context.running}"/>
		1421	<isfalse value="${context.stopped}"/>
		1422	</and>
		1423	</condition>
		1424	<condition property="context.deployable">
		1425	<or>
		1426	<istrue value="${context.notInstalled}"/>
		1427	<and>
		1428	<istrue value="${context.running}"/>
		1429	<istrue value="${mgr.update}"/>
		1430	</and>
		1431	<and>
		1432	<istrue value="${context.stopped}"/>
		1433	<istrue value="${mgr.update}"/>
		1434	</and>
		1435	</or>
		1436	</condition>
		1437	<condition property="context.undeployable">
		1438	<or>
		1439	<istrue value="${context.running}"/>
		1440	<istrue value="${context.stopped}"/>
		1441	</or>
		1442	</condition>
		1443	</target></code></pre></div>
		1444
		1445	<p><strong>WARNING:</strong> even if it doesn't make many sense, and is always a bad idea,
		1446	calling a Catalina task more than once,
		1447	badly set Ant tasks depends chains may cause that a task be called
		1448	more than once in the same Ant run, even if not intended to. A bit of caution should be exercised when you are
		1449	capturing output from that task, because this could lead to something unexpected:</p>
		1450	<ul>
		1451	<li>when capturing in a property you will find in it only the output from the <em>first</em> call, because
		1452	Ant properties are immutable and once set they cannot be changed,
		1453	</li>
		1454	<li>when capturing in a file, each run will overwrite it and you will find in it only the <em>last</em> call
		1455	output, unless you are using the <code>append="true"</code> attribute, in which case you will
		1456	see the output of each task call appended to the file.
		1457	</li>
		1458	</ul>
		1459
		1460	</div></div>
		1461
		1462	</div></div></div></div></div><footer><div id="footer">
		1463	Copyright © 1999-2025, The Apache Software Foundation
		1464	<br>
		1465	Apache Tomcat, Tomcat, Apache, the Apache Tomcat logo and the Apache logo
		1466	are either registered trademarks or trademarks of the Apache Software
		1467	Foundation.
		1468	</div></footer></div></body></html>

Subversion Repositories Integrator Subversion

(root)/projeto-trade/apache-tomcat-9.0.112/webapps/docs/manager-howto.html - Rev 771