Gitiles
Code Review Sign In
source.supwisdom.com / portal_platform / tomcat-cms / 07b3087b89f4c23810bb2a7902fe5a06f392b984 / . / webapps / docs / html-manager-howto.html
blob: eac6a8c1682d81aadd038ac2ff8bc8e865712363 [file] [log] [blame]
Cheng Tang07b30872014-04-27 16:37:18 +0800[diff] [blame^]1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 7 (7.0.42) - Tomcat Web Application Manager How To</title><meta name="author" content="Glenn L. Nielsen"><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 </style><style type="text/css">
8 .wrapped-source code { display: block; background-color: transparent; }
9 .wrapped-source div { margin: 0 0 0 1.25em; }
10 .wrapped-source p { margin: 0 0 0 1.25em; text-indent: -1.25em; }
11 </style><style type="text/css">
12 p.notice {
13 border: 1px solid rgb(255, 0, 0);
14 background-color: rgb(238, 238, 238);
15 color: rgb(0, 51, 102);
16 padding: 0.5em;
17 margin: 1em 2em 1em 1em;
18 }
19 </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="
20 The Apache Tomcat Servlet/JSP Container
21 " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 7</font></h1><font face="arial,helvetica,sanserif">Version 7.0.42, Jul 2 2013</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="./images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></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</a></li><li><a href="ssi-howto.html">13) SSI</a></li><li><a href="cgi-howto.html">14) CGI</a></li><li><a href="proxy-howto.html">15) Proxy Support</a></li><li><a href="mbeans-descriptor-howto.html">16) MBean Descriptor</a></li><li><a href="default-servlet.html">17) Default Servlet</a></li><li><a href="cluster-howto.html">18) Clustering</a></li><li><a href="balancer-howto.html">19) Load Balancer</a></li><li><a href="connectors.html">20) Connectors</a></li><li><a href="monitoring.html">21) Monitoring and Management</a></li><li><a href="logging.html">22) Logging</a></li><li><a href="apr.html">23) APR/Native</a></li><li><a href="virtual-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="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>Tomcat Web Application Manager 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>
22<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Message">Message</a></li><li><a href="#Manager">Manager</a></li><li><a href="#Applications">Applications</a><ol><li><a href="#Start">Start</a></li><li><a href="#Stop">Stop</a></li><li><a href="#Reload">Reload</a></li><li><a href="#Undeploy">Undeploy</a></li></ol></li><li><a href="#Deploy">Deploy</a><ol><li><a href="#Deploy_directory_or_WAR_file_located_on_server">Deploy directory or WAR file located on server</a></li><li><a href="#Upload_a_WAR_file_to_install">Upload a WAR file to install</a></li><li><a href="#Deployment_Notes">Deployment Notes</a></li><li><a href="#Deploy_Message">Deploy Message</a></li></ol></li><li><a href="#Diagnostics">Diagnostics</a><ol><li><a href="#Finding_memory_leaks">Finding memory leaks</a></li></ol></li><li><a href="#Server_Information">Server Information</a></li></ul>
23</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>
24
25<p>In many production environments it is very useful to have the capability
26to manage your web applications without having to shut down and restart
27Tomcat. This document is for the HTML web interface to the web application
28<a href="manager-howto.html">manager</a>.</p>
29
30<p>The interface is divided into six sections:</p>
31<ul>
32 <li><strong>Message</strong> - Displays success and failure messages.</li>
33 <li><strong>Manager</strong> - General manager operations like list and
34 help.</li>
35 <li><strong>Applications</strong> - List of web applications and
36 commands.</li>
37 <li><strong>Deploy</strong> - Deploying web applications.</li>
38 <li><strong>Diagnostics</strong> - Identifying potential problems.</li>
39 <li><strong>Server Information</strong> - Information about the Tomcat
40 server.</li>
41</ul>
42
43</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Message"><strong>Message</strong></a></font></td></tr><tr><td><blockquote>
44
45<p>
46Displays information about the success or failure of the last web application
47manager command you performed. If it succeeded <strong>OK</strong> is displayed
48and may be followed by a success message. If it failed <strong>FAIL</strong>
49is displayed followed by an error message. Common failure messages are
50documented below for each command. The complete list of failure messages for
51each command can be found in the <a href="manager-howto.html">manager</a> web
52application documentation.
53</p>
54
55</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Manager"><strong>Manager</strong></a></font></td></tr><tr><td><blockquote>
56
57<p>The Manager section has three links:</p>
58<ul>
59 <li><strong>List Applications</strong> - Redisplay a list of web
60 applications.</li>
61 <li><strong>HTML Manager Help</strong> - A link to this document.</li>
62 <li><strong>Manager Help</strong> - A link to the comprehensive Manager
63 App HOW TO.</li>
64</ul>
65
66</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Applications"><strong>Applications</strong></a></font></td></tr><tr><td><blockquote>
67
68<p>The Applications section lists information about all the installed web
69applications and provides links for managing them. For each web application
70the following is displayed:</p>
71<ul>
72 <li><strong>Path</strong> - The web application context path.</li>
73 <li><strong>Display Name</strong> - The display name for the web application
74 if it has one configured in its "web.xml" file.</li>
75 <li><strong>Running</strong> - Whether the web application is running and
76 available (true), or not running and unavailable (false).</li>
77 <li><strong>Sessions</strong> - The number of active sessions for remote
78 users of this web application. The number of sessions is a link which
79 when submitted displays more details about session usage by the web
80 application in the Message box.</li>
81 <li><strong>Commands</strong> - Lists all commands which can be performed on
82 the web application. Only those commands which can be performed will be
83 listed as a link which can be submitted. No commands can be performed on
84 the manager web application itself. The following commands can be
85 performed:
86 <ul>
87 <li><strong>Start</strong> - Start a web application which had been
88 stopped.</li>
89 <li><strong>Stop</strong> - Stop a web application which is currently
90 running and make it unavailable.</li>
91 <li><strong>Reload</strong> - Reload the web application so that new
92 ".jar" files in <code>/WEB-INF/lib/</code> or new classes in
93 <code>/WEB-INF/classes/</code> can be used.</li>
94 <li><strong>Undeploy</strong> - Stop and then remove this web
95 application from the server.</li>
96 </ul>
97 </li>
98</ul>
99
100<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Start"><strong>Start</strong></a></font></td></tr><tr><td><blockquote>
101
102<p>Signal a stopped application to restart, and make itself available again.
103Stopping and starting is useful, for example, if the database required by
104your application becomes temporarily unavailable. It is usually better to
105stop the web application that relies on this database rather than letting
106users continuously encounter database exceptions.</p>
107
108<p>If this command succeeds, you will see a Message like this:</p>
109<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
110OK - Started application at context path /examples
111</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
112
113<p>Otherwise, the Message will start with <code>FAIL</code> and include an
114error message. Possible causes for problems include:</p>
115<ul>
116<li><em>Encountered exception</em>
117 <blockquote>
118 <p>An exception was encountered trying to start the web application.
119 Check the Tomcat logs for the details.</p>
120 </blockquote></li>
121<li><em>Invalid context path was specified</em>
122 <blockquote>
123 <p>The context path must start with a slash character, unless you are
124 referencing the ROOT web application -- in which case the context path
125 must be a zero-length string.</p>
126 </blockquote></li>
127<li><em>No context exists for path /foo</em>
128 <blockquote>
129 <p>There is no deployed application on the context path
130 that you specified.</p>
131 </blockquote></li>
132<li><em>No context path was specified</em>
133 <blockquote>
134 The <code>path</code> parameter is required.
135 </blockquote></li>
136</ul>
137
138</blockquote></td></tr></table>
139
140<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Stop"><strong>Stop</strong></a></font></td></tr><tr><td><blockquote>
141
142<p>Signal an existing application to make itself unavailable, but leave it
143deployed. Any request that comes in while an application is
144stopped will see an HTTP error 404, and this application will show as
145"stopped" on a list applications command.</p>
146
147<p>If this command succeeds, you will see a Message like this:</p>
148<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
149OK - Stopped application at context path /examples
150</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
151
152<p>Otherwise, the Message will start with <code>FAIL</code> and include an
153error message. Possible causes for problems include:</p>
154<ul>
155<li><em>Encountered exception</em>
156 <blockquote>
157 <p>An exception was encountered trying to stop the web application.
158 Check the Tomcat logs for the details.</p>
159 </blockquote></li>
160<li><em>Invalid context path was specified</em>
161 <blockquote>
162 <p>The context path must start with a slash character, unless you are
163 referencing the ROOT web application -- in which case the context path
164 must be a zero-length string.</p>
165 </blockquote></li>
166<li><em>No context exists for path /foo</em>
167 <blockquote>
168 <p>There is no deployed application on the context path
169 that you specified.</p>
170 </blockquote></li>
171<li><em>No context path was specified</em>
172 <blockquote>
173 The <code>path</code> parameter is required.
174 </blockquote></li>
175</ul>
176
177</blockquote></td></tr></table>
178
179<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Reload"><strong>Reload</strong></a></font></td></tr><tr><td><blockquote>
180
181<p>Signal an existing application to shut itself down and reload. This can
182be useful when the web application context is not reloadable and you have
183updated classes or property files in the <code>/WEB-INF/classes</code>
184directory or when you have added or updated jar files in the
185<code>/WEB-INF/lib</code> directory.
186</p>
187<p><strong>NOTE:</strong> The <code>/WEB-INF/web.xml</code>
188web application configuration file is not checked on a reload;
189the previous web.xml configuration is used.
190If you have made changes to your web.xml file you must stop
191then start the web application.
192</p>
193
194<p>If this command succeeds, you will see a Message like this:</p>
195<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
196OK - Reloaded application at context path /examples
197</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
198
199<p>Otherwise, the Message will start with <code>FAIL</code> and include an
200error message. Possible causes for problems include:</p>
201<ul>
202<li><em>Encountered exception</em>
203 <blockquote>
204 <p>An exception was encountered trying to restart the web application.
205 Check the Tomcat logs for the details.</p>
206 </blockquote></li>
207<li><em>Invalid context path was specified</em>
208 <blockquote>
209 <p>The context path must start with a slash character, unless you are
210 referencing the ROOT web application -- in which case the context path
211 must be a zero-length string.</p>
212 </blockquote></li>
213<li><em>No context exists for path /foo</em>
214 <blockquote>
215 <p>There is no deployed application on the context path
216 that you specified.</p>
217 </blockquote></li>
218<li><em>No context path was specified</em>
219 <blockquote>
220 The <code>path</code> parameter is required.
221 </blockquote></li>
222<li><em>Reload not supported on WAR deployed at path /foo</em>
223 <blockquote>
224 Currently, application reloading (to pick up changes to the classes or
225 <code>web.xml</code> file) is not supported when a web application is
226 installed directly from a WAR file, which happens when the host is
227 configured to not unpack WAR files. As it only works when the web
228 application is installed from an unpacked directory, if you are using
229 a WAR file, you should <code>undeploy</code> and then <code>deploy</code>
230 the application again to pick up your changes.
231 </blockquote></li>
232</ul>
233
234</blockquote></td></tr></table>
235
236<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Undeploy"><strong>Undeploy</strong></a></font></td></tr><tr><td><blockquote>
237
238<p><strong><font color="red">WARNING</font> - This command will delete the
239contents of the web application directory and/or ".war" file if it exists within
240the <code>appBase</code> directory (typically "webapps") for this virtual host
241</strong>. The web application temporary work directory is also deleted. If
242you simply want to take an application out of service, you should use the
243<code>/stop</code> command instead.</p>
244
245<p>Signal an existing application to gracefully shut itself down, and then
246remove it from Tomcat (which also makes this context path available for
247reuse later). This command is the logical opposite of the
248<code>/deploy</code> Ant command, and the related deploy features available
249in the HTML manager.</p>
250
251<p>If this command succeeds, you will see a Message like this:</p>
252<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
253OK - Undeployed application at context path /examples
254</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
255
256<p>Otherwise, the Message will start with <code>FAIL</code> and include an
257error message. Possible causes for problems include:</p>
258<ul>
259<li><em>Encountered exception</em>
260 <blockquote>
261 <p>An exception was encountered trying to undeploy the web application.
262 Check the Tomcat logs for the details.</p>
263 </blockquote></li>
264<li><em>Invalid context path was specified</em>
265 <blockquote>
266 <p>The context path must start with a slash character, unless you are
267 referencing the ROOT web application -- in which case the context path
268 must be a zero-length string.</p>
269 </blockquote></li>
270<li><em>No context exists for path /foo</em>
271 <blockquote>
272 <p>There is no deployed application on the context path
273 that you specified.</p>
274 </blockquote></li>
275<li><em>No context path was specified</em>
276 <blockquote>
277 The <code>path</code> parameter is required.
278 </blockquote></li>
279</ul>
280
281</blockquote></td></tr></table>
282
283</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Deploy"><strong>Deploy</strong></a></font></td></tr><tr><td><blockquote>
284
285<p>Web applications can be deployed using files or directories located
286on the Tomcat server or you can upload a web application archive (WAR)
287file to the server.</p>
288
289<p>To install an application, fill in the appropriate fields for the type
290of install you want to do and then submit it using the <i>Install</i>
291button.</p>
292
293<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Deploy directory or WAR file located on server"><!--()--></a><a name="Deploy_directory_or_WAR_file_located_on_server"><strong>Deploy directory or WAR file located on server</strong></a></font></td></tr><tr><td><blockquote>
294
295<p>Deploy and start a new web application, attached to the specified <i>Context
296Path:</i> (which must not be in use by any other web application).
297This command is the logical opposite of the <em>Undeploy</em> command.</p>
298
299<p>There are a number of different ways the deploy command can be used.</p>
300
301<h3>Deploy a Directory or WAR by URL</h3>
302
303<p>Install a web application directory or ".war" file located on the Tomcat
304server. If no <i>Context Path</i> is specified, the directory name or the
305war file name without the ".war" extension is used as the path. The
306<i>WAR or Directory URL</i> specifies a URL (including the <code>file:</code>
307scheme) for either a directory or a web application archive (WAR) file. The
308supported syntax for a URL referring to a WAR file is described on the Javadocs
309page for the <code>java.net.JarURLConnection</code> class. Use only URLs that
310refer to the entire WAR file.</p>
311
312<p>In this example the web application located in the directory
313<code>C:\path\to\foo</code> on the Tomcat server (running on Windows)
314is deployed as the web application context named <code>/footoo</code>.</p>
315<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
316Context Path: /footoo
317WAR or Directory URL: file:C:/path/to/foo
318</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
319
320
321<p>In this example the ".war" file <code>/path/to/bar.war</code> on the
322Tomcat server (running on Unix) is deployed as the web application
323context named <code>/bar</code>. Notice that there is no <code>path</code>
324parameter so the context path defaults to the name of the web application
325archive file without the ".war" extension.</p>
326<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
327WAR or Directory URL: jar:file:/path/to/bar.war!/
328</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
329
330
331<h3>Deploy a Directory or War from the Host appBase</h3>
332
333<p>Install a web application directory or ".war" file located in your Host
334appBase directory. If no <i>Context Path</i> is specified the directory name
335or the war file name without the ".war" extension is used as the path.</p>
336
337<p>In this example the web application located in a subdirectory named
338<code>foo</code> in the Host appBase directory of the Tomcat server is
339deployed as the web application context named <code>/foo</code>. Notice
340that there is no <code>path</code> parameter so the context path defaults
341to the name of the web application directory.</p>
342<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
343WAR or Directory URL: foo
344</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
345
346
347<p>In this example the ".war" file <code>bar.war</code> located in your
348Host appBase directory on the Tomcat server is deployed as the web
349application context named <code>/bartoo</code>.</p>
350<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
351Context Path: /bartoo
352WAR or Directory URL: bar.war
353</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
354
355
356<h3>Deploy using a Context configuration ".xml" file</h3>
357
358<p>If the Host deployXML flag is set to true, you can install a web
359application using a Context configuration ".xml" file and an optional
360".war" file or web application directory. The <i>Context Path</i>
361is not used when installing a web application using a context ".xml"
362configuration file.</p>
363
364<p>A Context configuration ".xml" file can contain valid XML for a
365web application Context just as if it were configured in your
366Tomcat <code>server.xml</code> configuration file. Here is an
367example for Tomcat running on Windows:</p>
368<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
369&lt;Context path="/foobar" docBase="C:\path\to\application\foobar"&gt;
370&lt;/Context&gt;
371</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
372
373
374<p>Use of the <i>WAR or Directory URL</i> is optional. When used
375to select a web application ".war" file or directory it overrides any
376docBase configured in the context configuration ".xml" file.</p>
377
378<p>Here is an example of installing an application using a Context
379configuration ".xml" file for Tomcat running on Windows.</p>
380<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
381XML Configuration file URL: file:C:/path/to/context.xml
382</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
383
384
385<p>Here is an example of installing an application using a Context
386configuration ".xml" file and a web application ".war" file located
387on the server (Tomcat running on Unix).</p>
388<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
389XML Configuration file URL: file:/path/to/context.xml
390WAR or Directory URL: jar:file:/path/to/bar.war!/
391</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
392
393
394</blockquote></td></tr></table>
395
396<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Upload a WAR file to install"><!--()--></a><a name="Upload_a_WAR_file_to_install"><strong>Upload a WAR file to install</strong></a></font></td></tr><tr><td><blockquote>
397
398<p>Upload a WAR file from your local system and install it into the
399appBase for your Host. The name of the WAR file without the ".war"
400extension is used as the context path name.</p>
401
402<p>Use the <i>Browse</i> button to select a WAR file to upload to the
403server from your local desktop system.</p>
404
405<p>The .WAR file may include Tomcat specific deployment configuration, by
406including a Context configuration XML file in
407<code>/META-INF/context.xml</code>.</p>
408
409<p>Upload of a WAR file could fail for the following reasons:</p>
410<ul>
411<li><em>File uploaded must be a .war</em>
412 <blockquote>
413 <p>The upload install will only accept files which have the filename
414 extension of ".war".</p>
415 </blockquote></li>
416<li><em>War file already exists on server</em>
417 <blockquote>
418 <p>If a war file of the same name already exists in your Host's
419 appBase the upload will fail. Either undeploy the existing war file
420 from your Host's appBase or upload the new war file using a different
421 name.</p>
422 </blockquote></li>
423<li><em>File upload failed, no file</em>
424 <blockquote>
425 <p>The file upload failed, no file was received by the server.</p>
426 </blockquote></li>
427<li><em>Install Upload Failed, Exception:</em>
428 <blockquote>
429 <p>The war file upload or install failed with a Java Exception.
430 The exception message will be listed.</p>
431 </blockquote></li>
432</ul>
433
434</blockquote></td></tr></table>
435
436<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>
437
438<p>If the Host is configured with unpackWARs=true and you install a war
439file, the war will be unpacked into a directory in your Host appBase
440directory.</p>
441
442<p>If the application war or directory is deployed in your Host appBase
443directory and either the Host is configured with autoDeploy=true the Context
444path must match the directory name or war file name without the ".war"
445extension.</p>
446
447<p>For security when untrusted users can manage web applications, the
448Host deployXML flag can be set to false. This prevents untrusted users
449from installing web applications using a configuration XML file and
450also prevents them from installing application directories or ".war"
451files located outside of their Host appBase.</p>
452
453</blockquote></td></tr></table>
454
455<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Deploy Message"><!--()--></a><a name="Deploy_Message"><strong>Deploy Message</strong></a></font></td></tr><tr><td><blockquote>
456
457<p>If deployment and startup is successful, you will receive a Message
458like this:</p>
459<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
460OK - Deployed application at context path /foo
461</pre></td><td bgcolor="#023264" width="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
462
463<p>Otherwise, the Message will start with <code>FAIL</code> and include an
464error message. Possible causes for problems include:</p>
465<ul>
466<li><em>Application already exists at path /foo</em>
467 <blockquote>
468 <p>The context paths for all currently running web applications must be
469 unique. Therefore, you must either undeploy the existing web
470 application using this context path, or choose a different context path
471 for the new one.</p>
472 </blockquote></li>
473<li><em>Document base does not exist or is not a readable directory</em>
474 <blockquote>
475 <p>The URL specified by the <i>WAR or Directory URL:</i> field must
476 identify a directory on this server that contains the "unpacked" version
477 of a web application, or the absolute URL of a web application archive
478 (WAR) file that contains this application. Correct the value entered for
479 the <i>WAR or Directory URL:</i> field.</p>
480 </blockquote></li>
481<li><em>Encountered exception</em>
482 <blockquote>
483 <p>An exception was encountered trying to start the new web application.
484 Check the Tomcat logs for the details, but likely explanations include
485 problems parsing your <code>/WEB-INF/web.xml</code> file, or missing
486 classes encountered when initializing application event listeners and
487 filters.</p>
488 </blockquote></li>
489<li><em>Invalid application URL was specified</em>
490 <blockquote>
491 <p>The URL for the <i>WAR or Directory URL:</i> field that you specified
492 was not valid. Such URLs must start with <code>file:</code>, and URLs
493 for a WAR file must end in ".war".</p>
494 </blockquote></li>
495<li><em>Invalid context path was specified</em>
496 <blockquote>
497 <p>The context path must start with a slash character, unless you are
498 referencing the ROOT web application -- in which case the context path
499 must be a "/" string.</p>
500 </blockquote></li>
501<li><em>Context path must match the directory or WAR file name:</em>
502 <blockquote>
503 If the application war or directory is deployed in your Host appBase
504 directory and either the Host is configured with autoDeploy=true the Context
505 path must match the directory name or war file name without the ".war"
506 extension.
507 </blockquote></li>
508<li><em>Only web applications in the Host web application directory can
509 be deployed</em>
510 <blockquote>
511 If the Host deployXML flag is set to false this error will happen
512 if an attempt is made to install a web application directory or
513 ".war" file outside of the Host appBase directory.
514 </blockquote></li>
515</ul>
516
517</blockquote></td></tr></table>
518</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Diagnostics"><strong>Diagnostics</strong></a></font></td></tr><tr><td><blockquote>
519
520<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>
521
522<p><strong>The find leaks diagnostic triggers a full garbage collection. It
523should be used with extreme caution on production systems.</strong></p>
524
525<p>The find leaks diagnostic attempts to identify web applications that have
526caused memory leaks when they were stopped, reloaded or undeployed. Results
527should always be confirmed
528with a profiler. The diagnostic uses additional functionality provided by the
529StandardHost implementation. It will not work if a custom host is used that
530does not extend StandardHost.</p>
531
532<p>This diagnostic will list context paths for the web applications that were
533stopped, reloaded or undeployed, but which classes from the previous runs
534are still present in memory, thus being a memory leak. If an application
535has been reloaded several times, it may be listed several times.</p>
536
537<p>Explicitly triggering a full garbage collection from Java code is documented
538to be unreliable. Furthermore, depending on the JVM used, there are options to
539disable explicit GC triggering, like <code>-XX:+DisableExplicitGC</code>.
540If you want to make sure, that the diagnostics were successfully running a full GC,
541you will need to check using tools like GC logging, JConsole or similar.</p>
542
543</blockquote></td></tr></table>
544</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 Information"><!--()--></a><a name="Server_Information"><strong>Server Information</strong></a></font></td></tr><tr><td><blockquote>
545
546<p>This section displays information about Tomcat, the operating system of
547the server Tomcat is hosted on, and the Java Virtual Machine Tomcat is
548running in.</p>
549
550</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
551 on improving documentation for Apache Tomcat.<br><br>
552 If you have trouble and need help, read
553 <a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page
554 and ask your question on the tomcat-users
555 <a href="http://tomcat.apache.org/lists.html">mailing list</a>.
556 Do not ask such questions here. This is not a Q&amp;A section.<br><br>
557 The Apache Comments System is explained <a href="/tomcat-7.0-doc/comments.html">here</a>.
558 Comments may be removed by our moderators if they are either
559 implemented or considered invalid/off-topic.</p><script type="text/javascript"><!--//--><![CDATA[//><!--
560 var comments_shortname = 'tomcat';
561 var comments_identifier = 'http://tomcat.apache.org/tomcat-7.0-doc/html-manager-howto.html';
562 (function(w, d) {
563 if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
564 d.write('<div id="comments_thread"><\/div>');
565 var s = d.createElement('script');
566 s.type = 'text/javascript';
567 s.async = true;
568 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
569 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
570 }
571 else {
572 d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.<\/strong><\/div>');
573 }
574 })(window, document);
575 //--><!]]></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>
576 Copyright &copy; 1999-2013, Apache Software Foundation
577 </em></font></div></td></tr></table></body></html>