Blame - tomcat-uidm/webapps/docs/manager-howto.html - UniIdentify/tomcat

blob: d28230a19a1d11634c5885231dd605c72d77b2fd [file] [log] [blame]

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