32
32
<section name="Table of Contents">
35
<a href="#Introduction">Introduction</a><br />
36
<a href="#Configuring Manager Application Access">
37
Configuring Manager Application Access</a><br />
38
<a href="#Supported Manager Commands">Supported Manager Commands</a><br />
40
<a href="#Deploy A New Application Remotely">Deploy A New Application Remotely</a><br />
41
<a href="#Deploy A New Application from a Local Path">Deploy A New Application from a Local Path</a><br />
42
<a href="#List Currently Deployed Applications">
43
List Currently Deployed Applications</a><br />
44
<a href="#Reload An Existing Application">Reload An Existing Application</a><br />
45
<a href="#List OS and JVM Properties">List OS and JVM Properties</a><br />
46
<a href="#List Available Global JNDI Resources">
47
List Available Global JNDI Resources</a><br />
48
<a href="#List Available Security Roles">List Available Security Roles</a><br />
49
<a href="#Session Statistics">Session Statistics</a><br />
50
<a href="#Start an Existing Application">Start an Existing Application</a><br />
51
<a href="#Stop an Existing Application">Stop an Existing Application</a><br />
52
<a href="#Undeploy an Existing Application">
53
Undeploy an Existing Application</a><br />
55
<a href="#Executing Manager Commands With Ant">
56
Executing Manager Commands With Ant</a><br />
57
<a href="#Using the JMX Proxy Servlet">
58
Using the JMX Proxy Servlet</a><br />
60
<a href="#What is JMX Proxy Servlet">What is JMX Proxy Servlet?</a><br />
61
<a href="#JMX Query command">Query command</a><br />
62
<a href="#JMX Set command">Set command</a><br />
68
36
<section name="Introduction">
102
70
Manager web application <code>Context</code> to a new host install the
103
71
<code>manager.xml</code> context configuration file in the
104
72
<code>$CATALINA_BASE/conf/[enginename]/[hostname]</code> folder. Here is an
107
75
<Context path="/manager" debug="0" privileged="true"
108
76
docBase="/usr/local/kinetic/tomcat6/server/webapps/manager">
113
80
<p>If you have Tomcat configured to support multiple virtual hosts
114
81
(websites) you would need to configure a Manager for each.</p>
116
<p>There are three ways to use the <code>Manager</code> web application.
83
<p>There are three ways to use the <code>Manager</code> web application.</p>
118
85
<li>As an application with a user interface you use in your browser.
119
86
Here is an example URL where you can replace <code>localhost</code> with
128
95
<a href="#Executing Manager Commands With Ant">Executing Manager Commands
129
96
With Ant</a> for more information.</li>
135
101
<section name="Configuring Manager Application Access">
138
<p>The description below uses the variable name $CATALINA_BASE to refer the
104
<p><em>The description below uses the variable name $CATALINA_BASE to refer the
139
105
base directory against which most relative paths are resolved. If you have
140
106
not configured Tomcat 6 for multiple instances by setting a CATALINA_BASE
141
107
directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
142
the directory into which you have installed Tomcat 6.</p>
108
the directory into which you have installed Tomcat 6.</em></p>
145
111
<p>It would be quite unsafe to ship Tomcat with default settings that allowed
146
112
anyone on the Internet to execute the Manager application on your server.
148
114
who attempts to use it must authenticate themselves, using a username and
149
115
password that have the role <strong>manager</strong> associated with them.
150
116
Further, there is no username in the default users file
151
(<conf>$CATALINA_BASE/conf/tomcat-users.xml</conf>) that is assigned this
117
(<code>$CATALINA_BASE/conf/tomcat-users.xml</code>) that is assigned this
152
118
role. Therefore, access to the Manager application is completely disabled
194
160
<p>In addition to the password restrictions the manager web application
195
161
could be restricted by the remote IP address or host by adding a
196
162
<code>RemoteAddrValve</code> or <code>RemoteHostValve</code>. Here is
197
an example of restricting access to the localhost by IP address:
163
an example of restricting access to the localhost by IP address:</p>
199
165
<Context path="/manager" privileged="true"
200
166
docBase="/usr/local/kinetic/tomcat6/server/webapps/manager">
267
232
have been translated for your platform. The examples below show the English
268
233
version of the messages.</p>
271
<p><strong>WARNING:</strong> the legacy commands <code>/install</code> and
236
<p><em><strong>WARNING:</strong> the legacy commands <code>/install</code> and
272
237
<code>/remove</code> are deprecated.
273
238
They are presently equivalent to <code>/deploy</code> and <code>/undeploy</code>,
274
but could be removed in a future release.</p>
239
but could be removed in a future release.</em></p>
277
242
<subsection name="Deploy A New Application Remotely">
291
256
including a Context configuration XML file in
292
257
<code>/META-INF/context.xml</code>.</p>
294
<p>URL parameters include:
259
<p>URL parameters include:</p>
296
261
<li><code>update</code>: When set to true, any existing update will be
297
262
undeployed first. The default value is set to false.</li>
299
264
deployed webapp with a version number. The application version can
300
265
be later redeployed when needed using only the tag.</li>
304
268
<p><strong>NOTE</strong> - This command is the logical
305
269
opposite of the <code>/undeploy</code> command.</p>
348
312
<p>This can be used to deploy a previous version of a web application, which
349
313
has been deployed using the <code>tag</code> attribute. Note that the work
350
314
directory for the manager webapp will contain the previously deployed WARs;
351
removing it would make the deployment fail.
315
removing it would make the deployment fail.</p>
353
317
http://localhost:8080/manager/deploy?path=/footoo&tag=footag
357
321
<h3>Deploy a Directory or WAR by URL</h3>
368
332
<p>In this example the web application located in the directory
369
333
<code>/path/to/foo</code> on the Tomcat server is deployed as the
370
web application context named <code>/footoo</code>.
334
web application context named <code>/footoo</code>.</p>
372
336
http://localhost:8080/manager/deploy?path=/footoo&war=file:/path/to/foo
376
340
<p>In this example the ".war" file <code>/path/to/bar.war</code> on the
377
341
Tomcat server is deployed as the web application context named
378
342
<code>/bar</code>. Notice that there is no <code>path</code> parameter
379
343
so the context path defaults to the name of the web application archive
380
file without the ".war" extension.
344
file without the ".war" extension.</p>
382
346
http://localhost:8080/manager/deploy?war=jar:file:/path/to/bar.war!/
386
350
<h3>Deploy a Directory or War from the Host appBase</h3>
392
356
<p>In this example the web application located in a sub directory named
393
357
<code>foo</code> in the Host appBase directory of the Tomcat server is
394
358
deployed as the web application context named <code>/foo</code>. Notice
395
that the context path used is the name of the web application directory.
359
that the context path used is the name of the web application directory.</p>
397
361
http://localhost:8080/manager/deploy?war=foo
401
365
<p>In this example the ".war" file <code>bar.war</code> located in your
402
366
Host appBase directory on the Tomcat server is deployed as the web
403
application context named <code>/bar</code>.
367
application context named <code>/bar</code>.</p>
405
369
http://localhost:8080/manager/deploy?war=bar.war
409
373
<h3>Deploy using a Context configuration ".xml" file</h3>
417
381
<p>A Context configuration ".xml" file can contain valid XML for a
418
382
web application Context just as if it were configured in your
419
383
Tomcat <code>server.xml</code> configuration file. Here is an
422
386
<Context path="/foobar" docBase="/path/to/application/foobar"
433
397
<p>When the optional <code>war</code> parameter is set to the URL
434
398
for a web application ".war" file or directory it overrides any
435
399
docBase configured in the context configuration ".xml" file.</p>
437
401
<p>Here is an example of deploying an application using a Context
438
configuration ".xml" file.
402
configuration ".xml" file.</p>
440
404
http://localhost:8080/manager/deploy?config=file:/path/context.xml
444
408
<p>Here is an example of deploying an application using a Context
445
409
configuration ".xml" file and a web application ".war" file located
448
412
http://localhost:8080/manager/deploy?config=file:/path/context.xml&war=jar:file:/path/bar.war!/
452
416
<h3>Deployment Notes</h3>
864
<subsection name="Finding memory leaks">
867
http://localhost:8080/manager/findleaks
870
<p><strong>The find leaks diagnostic triggers a full garbage collection. It
871
should be used with extreme caution on production systems.</strong></p>
873
<p>The find leaks diagnostic attempts to identify web applications that have
874
caused memory leaks when they were stopped, reloaded or undeployed. Results
875
should always be confirmed
876
with a profiler. The diagnostic uses additional functionality provided by the
877
StandardHost implementation. It will not work if a custom host is used that
878
does not extend StandardHost.</p>
880
<p>Explicitly triggering a full garbage collection from Java code is documented
881
to be unreliable. Furthermore, depending on the JVM used, there are options to
882
disable explicit GC triggering, like <code>-XX:+DisableExplicitGC</code>.
883
If you want to make sure, that the diagnostics were successfully running a full GC,
884
you will need to check using tools like GC logging, JConsole or similar.</p>
886
<p>If this command succeeds, you will see a response like this:</p>
891
<p>Each context path for a web application that was stopped, reloaded or
892
undeployed, but which classes from the previous runs are still loaded in memory,
893
thus causing a memory leak, will be listed on a new line. If an application
894
has been reloaded several times, it may be listed several times.</p>
896
<p>If the command does not succeed, the response will start with
897
<code>FAIL</code> and include an error message.</p>
900
901
<subsection name="Server Status">
902
903
<p>From this link , you can view information about the server.</p>
1224
1225
calling a Catalina task more than once,
1225
1226
badly set Ant tasks depends chains may cause that a task be called
1226
1227
more than once in the same Ant run, even if not intended to. A bit of caution should be exercised when you are
1227
capturing output from that task, because this could lead to something unexpected:
1228
capturing output from that task, because this could lead to something unexpected:</p>
1229
1230
<li>when capturing in a property you will find in it only the output from the <em>first</em> call, because
1230
1231
Ant properties are immutable and once set they cannot be changed,
added
removed
webapps/docs/manager-howto.xml
