source: nutchez-0.1/tomcat/webapps/docs/html-manager-howto.html @ 141

Last change on this file since 141 was 66, checked in by waue, 16 years ago

NutchEz - an easy way to nutch
File size: 40.8 KB
Line 
1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 6.0 - Tomcat Web Application Manager How To</title><meta value="Glenn L. Nielsen" name="author"><meta value="glenn@apache.org" name="email"></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img border="0" alt="
2      The Apache Tomcat Servlet/JSP Container
3    " align="right" src="./images/tomcat.gif"></a></td><td><font face="arial,helvetica,sanserif"><h1>Apache Tomcat 6.0</h1></font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img border="0" alt="Apache Logo" align="right" src="./images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><tr><!--LEFT SIDE NAVIGATION--><td nowrap="true" valign="top" width="20%"><p><strong>Links</strong></p><ul><li><a href="index.html">Docs Home</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li></ul><p><strong>User Guide</strong></p><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="appdev/index.html">3) First webapp</a></li><li><a href="deployer-howto.html">4) Deployer</a></li><li><a href="manager-howto.html">5) Manager</a></li><li><a href="realm-howto.html">6) Realms and AAA</a></li><li><a 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></ul><p><strong>Reference</strong></p><ul><li><a href="RELEASE-NOTES.txt">Release Notes</a></li><li><a href="config/index.html">Configuration</a></li><li><a href="api/index.html">Javadocs</a></li><li><a href="http://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul><p><strong>Apache Tomcat Development</strong></p><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="http://wiki.apache.org/tomcat/TomcatVersions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="funcspecs/index.html">Functional Specs.</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td align="left" valign="top" width="80%"><table cellspacing="4" width="100%" border="0"><tr><td valign="top" align="left"><h1>Apache Tomcat 6.0</h1><h2>Tomcat Web Application Manager How To</h2></td><td nowrap="true" valign="top" align="right"><small><a href="printer/html-manager-howto.html"><img alt="Printer Friendly Version" border="0" src="./images/printer.gif"><br>print-friendly<br>version
4                    </a></small></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
5
6<p>In many production environments it is very useful to have the capability
7to manage your web applications without having to shut down and restart
8Tomcat.  This document is for the HTML web interface to the web application
9<a href="manager-howto.html">manager</a>.</p>
10
11<p>The interface is divided into five sections:
12<ul>
13  <li><strong>Message</strong> - Displays success and failure messages.</li>
14  <li><strong>Manager</strong> - General manager operations like list and
15      help.</li>
16  <li><strong>Applications</strong> - List of web applications and
17      commands.</li>
18  <li><strong>Deploy</strong> - Deploying web applications.</li>
19  <li><strong>Server Information</strong> - Information about the Tomcat
20      server.</li>
21</ul>
22</p>
23
24</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Message"><strong>Message</strong></a></font></td></tr><tr><td><blockquote>
25
26<p>
27Displays information about the success or failure of the last web application
28manager command you performed. If it succeeded <strong>OK</strong> is displayed
29and may be followed by a success message. If it failed <strong>FAIL</strong>
30is displayed followed by an error message. Common failure messages are
31documented below for each command.  The complete list of failure messages for
32each command can be found in the <a href="manager-howto.html">manager</a> web
33application documentation.
34</p>
35
36</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Manager"><strong>Manager</strong></a></font></td></tr><tr><td><blockquote>
37
38<p>The Manager section has three links:
39<ul>
40  <li><strong>List Applications</strong> - Redisplay a list of web
41      applications.</li>
42  <li><strong>HTML Manager Help</strong> - A link to this document.</li>
43  <li><strong>Manager Help</strong> - A link to the comprehensive Manager
44      App HOW TO.</li>
45</ul>
46</p>
47
48</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Applications"><strong>Applications</strong></a></font></td></tr><tr><td><blockquote>
49
50<p>The Applications section lists information about all the installed web
51applications and provides links for managing them. For each web application
52the following is displayed:
53<ul>
54  <li><strong>Path</strong> - The web applicaton context path.</li>
55  <li><strong>Display Name</strong> - The display name for the web application
56      if it has one configured in its "web.xml" file.</li>
57  <li><strong>Running</strong> - Whether the web application is running and
58      available (true), or not running and unavailable (false).</li>
59  <li><strong>Sessions</strong> - The number of active sessions for remote
60      users of this web application.  The number of sessions is a link which
61      when submitted displays more details about session usage by the web
62      application in the Message box.</li>
63  <li><strong>Commands</strong> - Lists all commands which can be performed on
64      the web application. Only those commands which can be performed will be
65      listed as a link which can be submitted. No commands can be performed on
66      the manager web application itself. The following commands can be
67      performed:
68      <ul>
69        <li><strong>Start</strong> - Start a web application which had been
70            stopped.</li>
71        <li><strong>Stop</strong> - Stop a web application which is currently
72            running and make it unavailable.</li>
73        <li><strong>Reload</strong> - Reload the web application so that new
74            ".jar" files in <code>/WEB-INF/lib/</code> or new classes in
75            <code>/WEB-INF/classes/</code> can be used.</li>
76        <li><strong>Undeploy</strong> - Stop and then remove this web
77             application from the server.</li>
78      </ul>
79  </li>
80</ul>
81</p>
82
83<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Start"><strong>Start</strong></a></font></td></tr><tr><td><blockquote>
84
85<p>Signal a stopped application to restart, and make itself available again.
86Stopping and starting is useful, for example, if the database required by
87your application becomes temporarily unavailable.  It is usually better to
88stop the web application that relies on this database rather than letting
89users continuously encounter database exceptions.</p>
90
91<p>If this command succeeds, you will see a Message like this:</p>
92<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
93OK - Started application at context path /examples
94</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr></table></div>
95
96<p>Otherwise, the Message will start with <code>FAIL</code> and include an
97error message.  Possible causes for problems include:
98<ul>
99<li><em>Encountered exception</em>
100    <blockquote>             
101    <p>An exception was encountered trying to start the web application.
102    Check the Tomcat 6 logs for the details.</p>
103    </blockquote></li>       
104<li><em>Invalid context path was specified</em>
105    <blockquote>             
106    <p>The context path must start with a slash character, unless you are
107    referencing the ROOT web application -- in which case the context path
108    must be a zero-length string.</p>
109    </blockquote></li>       
110<li><em>No context exists for path /foo</em>
111    <blockquote>             
112    <p>There is no deployed application on the context path
113    that you specified.</p> 
114    </blockquote></li>       
115<li><em>No context path was specified</em>
116    <blockquote>             
117    The <code>path</code> parameter is required.
118    </blockquote></li>       
119</ul>
120</p>
121
122</blockquote></td></tr></table>
123
124<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Stop"><strong>Stop</strong></a></font></td></tr><tr><td><blockquote>
125
126<p>Signal an existing application to make itself unavailable, but leave it
127deployed.  Any request that comes in while an application is
128stopped will see an HTTP error 404, and this application will show as
129"stopped" on a list applications command.</p>
130                             
131<p>If this command succeeds, you will see a Message like this:</p>
132<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
133OK - Stopped application at context path /examples
134</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr></table></div>
135                             
136<p>Otherwise, the Message will start with <code>FAIL</code> and include an
137error message.  Possible causes for problems include:
138<ul>                         
139<li><em>Encountered exception</em>
140    <blockquote>             
141    <p>An exception was encountered trying to stop the web application.
142    Check the Tomcat 6 logs for the details.</p>
143    </blockquote></li>       
144<li><em>Invalid context path was specified</em>
145    <blockquote>             
146    <p>The context path must start with a slash character, unless you are
147    referencing the ROOT web application -- in which case the context path
148    must be a zero-length string.</p>
149    </blockquote></li>       
150<li><em>No context exists for path /foo</em>
151    <blockquote>             
152    <p>There is no deployed application on the context path
153    that you specified.</p> 
154    </blockquote></li>       
155<li><em>No context path was specified</em>
156    <blockquote>             
157    The <code>path</code> parameter is required.
158    </blockquote></li>       
159</ul>
160</p>
161
162</blockquote></td></tr></table>
163
164<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Reload"><strong>Reload</strong></a></font></td></tr><tr><td><blockquote>
165
166<p>Signal an existing application to shut itself down and reload.  This can
167be useful when the web application context is not reloadable and you have
168updated classes or property files in the <code>/WEB-INF/classes</code>
169directory or when you have added or updated jar files in the
170<code>/WEB-INF/lib</code> directory.
171</p>
172<p><strong>NOTE:</strong> The <code>/WEB-INF/web.xml</code>
173web application configuration file is not checked on a reload;
174the previous web.xml configuration is used.
175If you have made changes to your web.xml file you must stop
176then start the web application.
177</p>
178
179<p>If this command succeeds, you will see a Message like this:</p>
180<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
181OK - Reloaded application at context path /examples
182</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr></table></div>
183
184<p>Otherwise, the Message will start with <code>FAIL</code> and include an
185error message.  Possible causes for problems include:
186<ul>
187<li><em>Encountered exception</em>
188    <blockquote>             
189    <p>An exception was encountered trying to restart the web application.
190    Check the Tomcat 6 logs for the details.</p>
191    </blockquote></li>       
192<li><em>Invalid context path was specified</em>
193    <blockquote>             
194    <p>The context path must start with a slash character, unless you are
195    referencing the ROOT web application -- in which case the context path
196    must be a zero-length string.</p>
197    </blockquote></li>       
198<li><em>No context exists for path /foo</em>
199    <blockquote>             
200    <p>There is no deployed application on the context path
201    that you specified.</p> 
202    </blockquote></li>       
203<li><em>No context path was specified</em>
204    <blockquote>             
205    The <code>path</code> parameter is required.
206    </blockquote></li>       
207<li><em>Reload not supported on WAR deployed at path /foo</em>
208    <blockquote>             
209    Currently, application reloading (to pick up changes to the classes or
210    <code>web.xml</code> file) is not supported when a web application is
211    installed directly from a WAR file, which happens when the host is
212    configured to not unpack WAR files. As it only works when the web
213    application is installed from an unpacked directory, if you are using
214    a WAR file, you should <code>undeploy</code> and then <code>deploy</code> 
215    the application again to pick up your changes.
216    </blockquote></li>       
217</ul>
218</p>
219
220</blockquote></td></tr></table>
221
222<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Undeploy"><strong>Undeploy</strong></a></font></td></tr><tr><td><blockquote>
223
224<p><strong><font color="red">WARNING</font> - This command will delete the
225contents of the web application directory and/or ".war" file if it exists within
226the <code>appBase</code> directory (typically "webapps") for this virtual host
227</strong>.  The web application temporary work directory is also deleted.  If
228you simply want to take an application out of service, you should use the
229<code>/stop</code> command instead.</p>
230                             
231<p>Signal an existing application to gracefully shut itself down, and then
232remove it from Tomcat (which also makes this context path available for
233reuse later).  This command is the logical opposite of the
234<code>/deploy</code> Ant command, and the related deploy features available
235in the HTML manager.</p>
236                             
237<p>If this command succeeds, you will see a Message like this:</p>
238<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
239OK - Undeployed application at context path /examples
240</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr></table></div>
241                             
242<p>Otherwise, the Message will start with <code>FAIL</code> and include an
243error message.  Possible causes for problems include:
244<ul>                         
245<li><em>Encountered exception</em>
246    <blockquote>             
247    <p>An exception was encountered trying to undeploy the web application.
248    Check the Tomcat logs for the details.</p>
249    </blockquote></li>       
250<li><em>Invalid context path was specified</em>
251    <blockquote>             
252    <p>The context path must start with a slash character, unless you are
253    referencing the ROOT web application -- in which case the context path
254    must be a zero-length string.</p>
255    </blockquote></li>       
256<li><em>No context exists for path /foo</em>
257    <blockquote>             
258    <p>There is no deployed application on the context path
259    that you specified.</p> 
260    </blockquote></li>       
261<li><em>No context path was specified</em>
262    <blockquote>             
263    The <code>path</code> parameter is required.
264    </blockquote></li>       
265</ul>
266</p>
267
268</blockquote></td></tr></table>
269
270</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Deploy"><strong>Deploy</strong></a></font></td></tr><tr><td><blockquote>
271
272<p>Web applications can be deployed using files or directories located
273on the Tomcat server or you can upload a web application archive (WAR)
274file to the server.</p>
275
276<p>To install an application, fill in the appropriate fields for the type
277of install you want to do and then submit it using the <i>Install</i>
278button.</p>
279
280<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><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>
281
282<p>Deploy and start a new web application, attached to the specified <i>Context
283Path:</i> (which must not be in use by any other web application).
284This command is the logical opposite of the <em>Undeploy</em> command.</p>
285
286<p>There are a number of different ways the deploy command can be used.</p>
287
288<h3>Deploy a Directory or WAR by URL</h3>
289
290<p>Install a web application directory or ".war" file located on the Tomcat
291server. If no <i>Context Path</i> is specified, the directory name or the
292war file name without the ".war" extension is used as the path. The
293<i>WAR or Directory URL</i> specifies a URL (including the <code>file:</code>
294scheme) for either a directory or a web application archive (WAR) file. The
295supported syntax for a URL referring to a WAR file is described on the Javadocs
296page for the <code>java.net.JarURLConnection</code> class.  Use only URLs that
297refer to the entire WAR file.</p>
298
299<p>In this example the web application located in the directory
300<code>C:\path\to\foo</code> on the Tomcat server (running on Windows)
301is deployed as the web application context named <code>/footoo</code>.
302<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
303Context Path: /footoo
304WAR or Directory URL: file:C:/path/to/foo
305</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr></table></div>
306</p>
307
308<p>In this example the ".war" file <code>/path/to/bar.war</code> on the
309Tomcat server (running on Unix) is deployed as the web application
310context named <code>/bar</code>. Notice that there is no <code>path</code>
311parameter so the context path defaults to the name of the web application
312archive file without the ".war" extension.
313<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
314WAR or Directory URL: jar:file:/path/to/bar.war!/
315</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr></table></div>
316</p>
317
318<h3>Deploy a Directory or War from the Host appBase</h3>
319
320<p>Install a web application directory or ".war" file located in your Host
321appBase directory. If no <i>Context Path</i> is specified the directory name
322or the war file name without the ".war" extension is used as the path.</p>
323
324<p>In this example the web application located in a subdirectory named
325<code>foo</code> in the Host appBase directory of the Tomcat server is
326deployed as the web application context named <code>/foo</code>. Notice
327that there is no <code>path</code> parameter so the context path defaults
328to the name of the web application directory.
329<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
330WAR or Directory URL: foo
331</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr></table></div>
332</p>
333
334<p>In this example the ".war" file <code>bar.war</code> located in your
335Host appBase directory on the Tomcat server is deployed as the web
336application context named <code>/bartoo</code>.
337<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
338Context Path: /bartoo
339WAR or Directory URL: bar.war
340</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr></table></div>
341</p>
342
343<h3>Deploy using a Context configuration ".xml" file</h3>
344
345<p>If the Host deployXML flag is set to true, you can install a web
346application using a Context configuration ".xml" file and an optional
347".war" file or web application directory. The <i>Context Path</i>
348is not used when installing a web application using a context ".xml"
349configuration file.</p>
350
351<p>A Context configuration ".xml" file can contain valid XML for a
352web application Context just as if it were configured in your
353Tomcat <code>server.xml</code> configuration file. Here is an
354example for Tomcat running on Windows:
355<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
356&lt;Context path="/foobar" docBase="C:\path\to\application\foobar"
357         debug="0"&gt;
358
359  &lt;!-- Link to the user database we will get roles from --&gt;
360  &lt;ResourceLink name="users" global="UserDatabase"
361                type="org.apache.catalina.UserDatabase"/&gt;
362
363&lt;/Context&gt;
364</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr></table></div>
365</p>
366
367<p>Use of the <i>WAR or Directory URL</i> is optional. When used
368to select a web application ".war" file or directory it overrides any
369docBase configured in the context configuration ".xml" file.</p>
370
371<p>Here is an example of installing an application using a Context
372configuration ".xml" file for Tomcat running on Windows.
373<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
374XML Configuration file URL: file:C:/path/to/context.xml
375</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr></table></div>
376</p>
377
378<p>Here is an example of installing an application using a Context
379configuration ".xml" file and a web application ".war" file located
380on the server (Tomcat running on Unix).
381<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
382XML Configuration file URL: file:/path/to/context.xml
383WAR or Directory URL: jar:file:/path/to/bar.war!/
384</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr></table></div>
385</p>
386
387</blockquote></td></tr></table>
388
389<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Upload a WAR file to install"><strong>Upload a WAR file to install</strong></a></font></td></tr><tr><td><blockquote>
390
391<p>Upload a WAR file from your local system and install it into the
392appBase for your Host. The name of the WAR file without the ".war"
393extension is used as the context path name.</p>
394
395<p>Use the <i>Browse</i> button to select a WAR file to upload to the
396server from your local desktop system.</p>
397
398<p>The .WAR file may include Tomcat specific deployment configuration, by
399including a Context configuration XML file in
400<code>/META-INF/context.xml</code>.</p>
401
402<p>Upload of a WAR file could fail for the following reasons:</p>
403<ul>
404<li><em>File uploaded must be a .war</em>
405    <blockquote>
406    <p>The upload install will only accept files which have the filename
407    extension of ".war".</p>
408    </blockquote></li>
409<li><em>War file already exists on server</em>
410    <blockquote>
411    <p>If a war file of the same name already exists in your Host's
412    appBase the upload will fail. Either undeploy the existing war file
413    from your Host's appBase or upload the new war file using a different
414    name.</p>
415    </blockquote></li>
416<li><em>File upload failed, no file</em>
417    <blockquote>
418    <p>The file upload failed, no file was received by the server.</p>
419    </blockquote></li>
420<li><em>Install Upload Failed, Exception:</em>
421    <blockquote>
422    <p>The war file upload or install failed with a Java Exception.
423    The exception message will be listed.</p>
424    </blockquote></li>
425</ul>
426
427</blockquote></td></tr></table>
428
429<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Deployment Notes"><strong>Deployment Notes</strong></a></font></td></tr><tr><td><blockquote>
430
431<p>If the Host is configured with unpackWARs=true and you install a war
432file, the war will be unpacked into a directory in your Host appBase
433directory.</p>
434
435<p>If the application war or directory is deployed in your Host appBase
436directory and either the Host is configured with autoDeploy=true or
437liveDeploy=true, the Context path must match the directory name or
438war file name without the ".war" extension.</p>
439
440<p>For security when untrusted users can manage web applications, the
441Host deployXML flag can be set to false.  This prevents untrusted users
442from installing web applications using a configuration XML file and
443also prevents them from installing application directories or ".war"
444files located outside of their Host appBase.</p>
445
446</blockquote></td></tr></table>
447
448<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Deploy Message"><strong>Deploy Message</strong></a></font></td></tr><tr><td><blockquote>
449
450<p>If deployment and startup is successful, you will receive a Message
451like this:</p>
452<div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre>
453OK - Deployed application at context path /foo
454</pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="./images/void.gif"></td></tr></table></div>
455
456<p>Otherwise, the Message will start with <code>FAIL</code> and include an
457error message.  Possible causes for problems include:</p>
458<ul>
459<li><em>Application already exists at path /foo</em>
460    <blockquote>
461    <p>The context paths for all currently running web applications must be
462    unique.  Therefore, you must either undeploy the existing web
463    application using this context path, or choose a different context path
464    for the new one.</p>
465    </blockquote></li>
466<li><em>Document base does not exist or is not a readable directory</em>
467    <blockquote>
468    <p>The URL specified by the <i>WAR or Directory URL:</i> field must
469    identify a directory on this server that contains the "unpacked" version
470    of a web application, or the absolute URL of a web application archive
471    (WAR) file that contains this application.  Correct the value entered for
472    the <i>WAR or Directory URL:</i> field.</p>
473    </blockquote></li>
474<li><em>Encountered exception</em>
475    <blockquote>
476    <p>An exception was encountered trying to start the new web application.
477    Check the Tomcat 6 logs for the details, but likely explanations include
478    problems parsing your <code>/WEB-INF/web.xml</code> file, or missing
479    classes encountered when initializing application event listeners and
480    filters.</p>
481    </blockquote></li>
482<li><em>Invalid application URL was specified</em>
483    <blockquote>
484    <p>The URL for the <i>WAR or Directory URL:</i> field that you specified
485    was not valid.  Such URLs must start with <code>file:</code>, and URLs
486    for a WAR file must end in ".war".</p>
487    </blockquote></li>
488<li><em>Invalid context path was specified</em>
489    <blockquote>
490    <p>The context path must start with a slash character, unless you are
491    referencing the ROOT web application -- in which case the context path
492    must be a "/" string.</p>
493    </blockquote></li>
494<li><em>Context path must match the directory or WAR file name:</em>
495    <blockquote>
496    If the application war or directory is deployed in your Host appBase
497    directory and either the Host is configured with autoDeploy=true or
498    liveDeploy=true, the Context path must match the directory name or
499    war file name without the ".war" extension.
500    </blockquote></li>
501<li><em>Only web applications in the Host web application directory can
502     be deployed</em>
503     <blockquote>
504     If the Host deployXML flag is set to false this error will happen
505     if an attempt is made to install a web application directory or
506      ".war" file outside of the Host appBase directory.
507     </blockquote></li>
508</ul>
509
510</blockquote></td></tr></table>
511</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Server Information"><strong>Server Information</strong></a></font></td></tr><tr><td><blockquote>
512
513<p>This section displays information about Tomcat, the operating system of
514the server Tomcat is hosted on, and the Java Virtual Machine Tomcat is
515running in.</p>
516
517</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em>
518        Copyright &copy; 1999-2008, Apache Software Foundation
519        </em></font></div></td></tr></table></body></html>
Note: See TracBrowser for help on using the repository browser.