Tomcat- 5.Tomcat Manager

1. 概述

Tomcat Manager用来解决以下问题：

• 无需关闭或者重启tomcat的情况下，重新部署web应用或者取消对现有应用的部署
• 在Tomcat服务器配置文件中没有指定reloadable的情况下，也可以请求重新加载现有应用。

Tomcat Manager默认安装在上下文路径：/manager中，支持的功能有：

• 用已上传的WAR文件内容部署新的web应用
• 在服务器文件系统中指定的上下文路径部署新的web应用
• 列出当前已经部署的web应用，以及这些应用目前的活跃会话
• 重新加载现有的web应用，以便响应/WEB-INF/classes或/WEB-INF/lib中内容的更改
• 列出操作系统和JVM的属性值
• 列出可用的全局JNDI（Java Naming and Directory Interface,Java命名和目录接口）资源，将用于预备元素的部署工具中。元素内嵌于部署描述中。
• 开启一个已经停止的web应用，从而使其可以再次使用
• 停止一个现有的web应用，从而使其不可用，但是并不取消对他的部署
• 取消对一个以部署web应用的部署，删除它的文档库目录（除非是从文件系统中部署的）

Tomcat默认安装中已经包含了Manager，若要将Manager应用的实例上下文添加到一个新的主机中，manager.xml上下文配置文件应该放在$CATALINA_BASE/conf/[enginename]/[hostname]文件夹中：

如果要将Tomcat配置成能够支持多个虚拟机（网站），需要对每个虚拟机配置一个Manager。

Manager应用的使用方式有：

• 作为带有用户界面的应用，在浏览器中运行（localhost可以替换为主机名）：http://localhost:8080/manager/html
• 只使用HTTP请求的一个功能最少的版本，适合管理员通过创建脚本来使用。命令作为URI的一部分给出，响应时简单格式文本。
• 用于Ant构建工具的一套方便的任务来定义

2.配置Manager应用的访问

CATALINA_HOME（Tomcat的安装目录）
Manager应用要求用户在使用之前验证自己的身份，提供用户名和密码，以及相应配置的manager-*角色。
默认用户文件（$CATALINA_BASE/conf/tomcat-users.xml）中的用户名称都没有指定角色名称，所以默认不能访问Manager应用。

角色名称位于Manager应用的web.xml文件中，可用角色包括：

• manager-gui：能够访问HTML页面
• manager-status：只能访问“服务器状态”（Server Status）页面
• manager-script：能够访问文档中描述的适用于工具的纯文本页面，以及服务器状态页面
• manager-jmx：能够访问JMX代理页面以及服务器状态页面

如何配置用户名和密码取决于Realm实现：

• UserDataBaseRealm，MemoryUserDatabase，MemoryRealm：UserDatabaseRealm和MemoryUserDatabase配置在默认的$CATALINA_BASE/conf/server.xml文件中。MemoryUserDatabase和MemoryRealm会读取存储在$CATALINA_BASE/conf/tomcat-users.xml文件——它可以用任何文本编辑器编辑——它为每个用户定义了一个XML格式的：

3.易用的HTML界面

Manager应用的HTML界面位于：

http://{host}:{port}/manager/html

被赋予manager-gui角色的用户才能访问这个页面。
详细介绍参考：HTML Manger 文档

4.Manager支持的页面

Manager应用能够处理的命令都是通过下面的URL格式指定的：

http://{host}:{port}/manager/text/{command}?{parameter}

这些命令通常是被HTTP GET请求来执行的。
/deploy命令有一种能被HTTP PUT请求执行的格式。

4.1 常见参数

多数Manager 命令都能够接受一个或者多个查询参数：

• path：要处理的Web应用的上下文路径（包括前面的斜杠）。要选择ROOT Web应用，指定/即可。注意，无法对Manager应用本身执行管理命令
• version：并行部署所需要的Web应用版本号
• war Web应用归档（war）文件的URL，或者含有Web应用的目录路径名，或者是上下文配置 .xml文件。使用URL的格式有：
  • file:/absolute/path/to/a/directory 解压缩后的web应用所在的目录的绝对路径。不做任何改动，直接附加到所指定的上下文路径上
  • file:/absolute/path/to/a/webapp.war Web应用归档（war）文件的绝对路径，只对/deploy命令有效，也是该命令所唯一能接受的格式
  • jar:file:/absolute/path/to/a/warfile.war!/本地war文件的URL地址。为了完整引用一个jar文件，可以采用JarURLConnection类的任何有效语法。
  • file:/absolute/path/to/a/context.xml web应用上下文配置.xml文件的绝对路径，上下文配置文件包含着上下文配置元素
  • directory 主机应用的基本目录中的web应用的目录名称
  • webapp.war主机应用的基本目录中的war文件的名称

命令都会以text/plain形式返回响应。
响应的第一行用OK或者FAIL开头，标明请求命令是否成功。
如果响应失败，响应第一行随后部分会带有遇到问题的描述。

4.2 远程部署新应用

http://localhost:8080/manager/text/deploy?path=/foo

将所谓请求参数数据指定在HTTP PUT请求中的web应用归档文件（war）上传，将它安装在相应主机中的appBase目录中，然后启动，将war文件名添加到上述路径的appBase中
可以通过/undeploy命令取消对应用的部署，相应的应用目录也会被删除。

通过在/META-INF/context.xml中包含上下文配置XML文件，war文件能够包涵Tomcat特有的部署配置信息。

URL参数包括：

• update 设置为true时，任何已有的更新将会首先取消部署，默认值为false
• tag 指定一个标签名称，这个参数能够将已经部署的web应用与标签连接起来，如果web应用被取消部署，在以后重新部署时，使用标签就能实现

注意该命令和/undeploy命令在逻辑上是对立的。

安装或者启动成功会得到响应：

OK - Deployed application at context path /foo

否则，响应以FAIL开头，并包含错误信息。

4.3 从本地路径部署新的应用

部署并启动一个新的web应用，附加到指定的上下文path上（不能被其他web应用同时使用），该命令与/undeploy逻辑对立。

该命令由一个HTTP GET命令执行。部署命令的方式有很多：

4.3.1 部署之前部署过的web应用

http://localhost:8080/manager/text/deploy?path=/footoo&tag=footag

用来部署之前曾经通过tag属性部署过的web应用。
注意Manager应用的工作目录包含之前部署过的war文件：如果清除它将导致部署失败。

4.3.2 通过URL部署一个目录或者war文件

部署位于Tomcat服务器上的web应用或者war文件。如果没有指定上下文路径参数path，就会把目录名或者不带.war后缀的war文件名当作路径来使用。war参数制定了目录或者war文件的URL（也包含file:格式）。引用WAR文件的URL所采用的语法详见java.net.JarURLConnection类的Java文档页面。
只使用引用了整个war文件的URL。

例一：
web应用位于Tomcat服务器上的/path/to/foo目录中，被部署为上下文路径为/footoo的wen应用。

http://localhost:8080/manager/text/deploy?path=/footoo&war=file:/path/to/foo

例二：
Tomcat服务器上的war文件/path/tp/bar.war被部署为上下文路径为/bar的web应用。注意，这里没有path参数，因此上下文路径默认没有war后缀的war文件名。

http://localhost:8080/manager/text/deploy?war=file:/path/to/bar.war

4.3.2 从主机的appBase目录中部署一个目录或者war

对于主机appBase目录中的web应用目录或者war文件进行部署，目录名或者没有war后缀名的war文件名被用作上下文路径名。
例一：
web应用位于Tomcat服务器中主机appBase目录下名为foo的子目录中，被部署为路径名为/foo的web应用。注意用到的上下文路径就是web应用的目录名：

http://localhost:8080/manager/text/deploy?war=foo

例二：
位于主机appBase目录中的bar.war文件被部署为上下文名为/bar的web应用：

http://localhost:8080/manager/text/deploy?war=bar.war

4.3.4 使用上下文配置.xml文件进行部署

• 如果主机的deployXML标志设定为true，就可以使用上下文配置.xml文件以及一个可选的.war包（或web应用目录）来进行web应用部署。
• 在使用上下文.xml文件配置文件进行部署时，不会用到上下文路径参数/path。
• 上下文配置.xml文件包含用于web应用上下文的有效XML。范例：

• 可选的war参数被设定为指向web应用的war文件或者目录的URL，会覆盖掉上下文配置.xml文件中的docBase。

例一：
使用上下文配置.xml文件部署web应用：

http://localhost:8080/manager/text/deploy?config=file:/path/context.xml

例二：
使用上下文配置.xml文件和位于服务器中的web应用的war文件。

http://localhost:8080/manager/text/deploy
 ?config=file:/path/context.xml&war=file:/path/bar.war

4.3.5 注意事项

• 如果主机配置中将unpachWARs设定为true，并且部署了一个war文件，那么这个war文件将解压到主机的appBase目录下的一个目录中。
• 如果应用的war文件或者目录安装在主机的appBase目录中，那么，要么主机应该被部署为autoDeploy为true，或者上下文路径必须匹配目录名或者不带.war后缀的war文件名。
• 为了避免不可信用户对web应用的侵害，主机的deployXML标志可以设置为false，这能阻止了不可信用户通过使用XML配置文件来部署web应用，也能阻止他们部署位于主机appBase之外的应用目录或者.war文件

4.3.6 部署响应

安装和启动正常，响应为：

OK - Deployed application at context path /foo

否则，会返回以FAIL开头的错误信息：

• Application already exists at path /foo
  The context paths for all currently running web applications must be unique. Therefore, you must undeploy the existing web application using this context path, or choose a different context path for the new one. The update parameter may be specified as a parameter on the URL, with a value of true to avoid this error. In that case, an undeploy will be performed on an existing application before performing the deployment

• Document base does not exist or is not a readable directory
  The URL specified by the war parameter must identify a directory on this server that contains the "unpacked" version of a web application, or the absolute URL of a web application archive (WAR) file that contains this application. Correct the value specified by the war parameter.

• Encountered exception
  An exception was encountered trying to start the new web application. Check the Tomcat logs for the details, but likely explanations include problems parsing your /WEB-INF/web.xml file, or missing classes encountered when initializing application event listeners and filters.

• Invalid application URL was specified
  The URL for the directory or web application that you specified was not valid. Such URLs must start with file:, and URLs for a WAR file must end in ".war".

• Invalid context path was specified
  The context path must start with a slash character. To reference the ROOT web application use "/".

• Context path must match the directory or WAR file name:
  If the application war or directory is installed in your Host appBase directory and either the Host is configured with autoDeploy=true the Context path must match the directory name or war file name without the ".war" extension.

• Only web applications in the Host web application directory can be installed
  If the Host deployXML flag is set to false this error will happen if an attempt is made to deploy a web application directory or ".war" file outside of the Host appBase directory.

4.4 列出当前已部署应用

http://localhost:8080/manager/text/list

列出当前所有部署的web应用的上下文路径，当前路径（running或stopped），以及活跃的会话。
初始Tomcat一般会产生如下响应：

OK - Listed applications for virtual host [localhost]
/:running:0:ROOT
/examples:running:0:examples
/host-manager:running:0:host-manager
/manager:running:0:manager
/docs:running:0:docs

4.5 重新加载现有应用

http://localhost:8080/manager/text/reload?path=/examples

标记一个现有应用，关闭，并重新加载。使用情况为：当web应用上下文不能重新加载；已经更新了/WEB-INF/classes目录中的类和属性文件；或者在/WEB-INF/lib目录添加或更新了jar文件。

在重新加载时，web应用配置文件？WEB-INF/web.xml无法重新读区，如果对web.xml作出更改，必须重启web应用。

如果命令执行成功，响应为：

OK - Reloaded application at context path /examples

如果失败，回应以FAIL开头，并包含相关的错误信息，有以下几种：

• Encountered exception
  An exception was encountered trying to restart the web application. Check the Tomcat logs for the details.

• Invalid context path was specified
  The context path must start with a slash character. To reference the ROOT web application use "/".

• No context exists for path /foo
  There is no deployed application on the context path that you specified.

• No context path was specified
  The path parameter is required.

• Reload not supported on WAR deployed at path /foo
  Currently, application reloading (to pick up changes to the classes or web.xml file) is not supported when a web application is deployed directly from a WAR file. It only works when the web application is deployed from an unpacked directory. If you are using a WAR file, you should undeploy and then deploy or deploy with the update parameter the application again to pick up your changes.

4.6 列出OS和JVM属性

http://localhost:8080/manager/text/serverinfo

列出Tomcat版本，操作系统，以及JVM信息：

OK - Server info
Tomcat Version: Apache Tomcat/9.0.5
OS Name: Mac OS X
OS Version: 10.13.3
OS Architecture: x86_64
JVM Version: 1.8.0_161-b12
JVM Vendor: Oracle Corporation

出现错误，响应以FAIL开头，并包含错误信息：

* Encountered exception
An exception was encountered trying to enumerate the system properties. Check the Tomcat logs for the details.

4.7 列出可能的全局JNDI资源

http://localhost:8080/manager/text/resources[?type=xxxxx]

列出上下文配置文件资源链接中所使用的全局JNDI资源。如果指定type请求参数，参数值必须是所需资源类型的完整Java类名（例如javax.sql.DataSource获取所有可用的JDBC数据资源的名称），如果没有指定type请求参数，则返回所有类型的资源。
根据是否制定了type请求参数，响应成功第一行为：

OK - Listed global resources of all types

或

OK - Listed global resources of type xxxxx

之后每个资源单列一行，字段由冒号分割：

• Global Resource Name - The name of this global JNDI resource, which would be used in the global attribute of a element.全局JNDI资源的名称，将用在元素的global属性中。
• Global Resource Type - The fully qualified Java class name of this global JNDI resource.该全局JNDI资源的完整描述的Java类名。

出现错误，响应以FAIL开始，并包含一个错误消息：

• Encountered exception
  An exception was encountered trying to enumerate the global JNDI resources. Check the Tomcat logs for the details.

• No global JNDI resources are available
  The Tomcat server you are running has been configured without global JNDI resources.

4.8 会话统计

http://localhost:8080/manager/text/sessions?path=/examples

显示Web应用默认的会话超时，和当前活跃会话在一分钟内实际的超时次数。

OK - Session information for application at context path /examples
Default maximum session inactive interval 30 minutes
<1 minutes: 1 sessions
1 - <2 minutes: 1 sessions

4.9 过期会话

http://localhost:8080/manager/text/expire?path=/examples&idle=num

显示会话统计信息，以及超出nums所指定的分钟数的过期会话。想要使所有会话过期可以使用&idle=0
实际上，/sessions和/expire是同一个命令的两种异名，唯一不同的在于idle参数。

4.10 开启一个现有应用

http://localhost:8080/manager/text/start?path=/examples

标记一个已停止的应用，重新开启它，使得它再次可用。
如果正常，得到如下类似响应：

OK - Started application at context path [/examples]

否则，返回以FAIL开头的错误响应，并包含错误类型。

4.11 停止一个现有应用

标记一个现有应用，使其不可用，但是仍然处于已部署的状态。当应用停止时，任何请求都将得到HTTP 404.
如果命令执行成功，得到类似响应：

http://localhost:8080/manager/text/stop?path=/examples

否则，将得到以FAIL开头的错误信息。

4.12 取消对现有应用的部署

http://localhost:8080/manager/text/undeploy?path=/examples

WARNING：该命令将会删除主机appBase（通常是webapps）中所有的Web应用。

功能：标记一个已由应用，将它关闭，并从Tomcat中移除，如果文档根目录位于appBase目录（通常是webapps）中，那么它会被删除。
如果命令执行成功，得到如下响应：

OK - Undeployed application at context path /examples

否则，得到以FAIL开头的异常。

4.13 寻找内存泄漏

http://localhost:8080/manager/text/findleaks[?statusLine=[true|false]]

寻找内存泄漏的诊断将触发一次彻底的垃圾回收（GC），因此如果在生产环境中使用它需要非常谨慎。
该命令将会试图从已导致内存泄漏的web应用（当其处于停止，重新加载，以及被取消部署状态时）。通常由一种分析器来确认结论。诊断使用了由StandardHost（标准主机）所提供的附加功能。如果使用的是没有扩展自StandardHost的主机，则诊断无法生效。

Java中显示出发彻底的垃圾回收是不可能的。如果需要确认诊断是否成功实现了彻底的垃圾回收，可以使用GC日志，JConsole分析器或者类似工具。

执行成功返回：

/leaking-webapp

如果需要在响应中看到状态行，那么要在请求中加入statusLine查询参数。并将其设定为true。
对于已经停止的，被重新加载或取消部署的web应用，由于之前运行所需要的类仍然加载在内存中，从而造成内存泄漏。响应将把这种应用的每个上下文路径都单列一行。如果应用被加载了数次，就有可能被列出来数次。
如果命令没有成功执行，返回以FAIL开头的错误信息。

4.14 连接器SSL/TLS诊断

http://localhost:8080/manager/text/sslConnectorCiphers

SSL连接器/加密诊断会列出当前每一个连接器所配置的SSL/TLS加密算法，对于BIO和NIO，将列出每个加密算法套件的名称，对于APR，将返回SSLCipherSuite的值。
响应成功得到：

OK - Connector / SSL Cipher information
Connector[HTTP/1.1-8080]
  SSL is not enabled for this connector
Connector[HTTP/1.1-8443]
  TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA
  TLS_DHE_RSA_WITH_AES_128_CBC_SHA
  TLS_ECDH_RSA_WITH_AES_128_CBC_SHA
  TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA
  ...

4.15 线程转存

http://localhost:8080/manager/text/threaddump

编写JVM线程转存。
响应类似：

OK - JVM thread dump
2018-03-05 15:45:48.844
Full thread dump Java HotSpot(TM) 64-Bit Server VM (25.161-b12 mixed mode):

"ajp-nio-8009-exec-40" Id=106 cpu=148000 ns usr=65000 ns blocked 0 for -1 ms waited 1 for -1 ms
   java.lang.Thread.State: WAITING
    at sun.misc.Unsafe.park(Native Method)
    - waiting on (a java.util.concurrent.locks.AbstractQueuedSynchronizer$ConditionObject@7b46e563)
    at java.util.concurrent.locks.LockSupport.park(LockSupport.java:175)
    at java.util.concurrent.locks.AbstractQueuedSynchronizer$ConditionObject.await(AbstractQueuedSynchronizer.java:2039)
    at java.util.concurrent.LinkedBlockingQueue.take(LinkedBlockingQueue.java:442)
    at org.apache.tomcat.util.threads.TaskQueue.take(TaskQueue.java:103)
    at org.apache.tomcat.util.threads.TaskQueue.take(TaskQueue.java:31)
    at java.util.concurrent.ThreadPoolExecutor.getTask(ThreadPoolExecutor.java:1074)
    at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1134)
    at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:624)
    at org.apache.tomcat.util.threads.TaskThread$WrappingRunnable.run(TaskThread.java:61)
    at java.lang.Thread.run(Thread.java:748)

4.16 虚拟机（VM）信息

http://localhost:8080/manager/text/vminfo

写入一些关于Java虚拟机（VM）的诊断信息。
响应类似与：

OK - VM info
2018-03-05 16:07:42.660
Runtime information:
  vmName: Java HotSpot(TM) 64-Bit Server VM
  vmVersion: 25.161-b12
  vmVendor: Oracle Corporation
  specName: Java Virtual Machine Specification
  specVersion: 1.8
  specVendor: Oracle Corporation
  managementSpecVersion: 1.2
  name: [email protected]
  startTime: 1519977186974
  uptime: 149383638
  isBootClassPathSupported: true
...

4.17 保存配置信息

http://localhost:8080/manager/text/save

如果不置顶任何参数，该命令将吧服务器的当前配置信息保存到server.xml中，已有的配置信息.xml将被重命名，作为必要时的配置文件。
如果制定了path参数，而且该参数与已配置应用的路径相匹配，那么该web应用的配置将被保存为一个命名恰当的上下文.xml文件中，位于当前主机的xmlBase中。
要是用该命令，则在StoreConfigMBean需要存在，通常用StoreConfigLifecycleListener.
配置。
命令执行失败会返回以FAIL开头的错误信息。

5 服务器状态

可从下面链接中观察有关服务器的状态信息，任何一个**manager-****角色都可以访问这一页面。
用HTML格式显示的服务器状态信息：

http://localhost:8080/manager/status
http://localhost:8080/manager/status/all

用XML格式显示服务器状态信息：

http://localhost:8080/manager/status?XML=true
http://localhost:8080/manager/status/all?XML=true

首先显示的是服务器和JVM版本号，JVM提供者，操作系统名称，版本号，系统体系结构类型等。
其次是JVM内存使用信息。
最后是关于Tomcat AJP和HTTP连接器的信息，对两者来说，这些信息很有用：

• 线程信息：最大线程数，最少和最多的空闲线程数，当前线程数量以及当前繁忙线程。
• 请求信息：最长以及最短的处理时间，请求和错误数量，以及接受和发送的字节数量
• 一张完整显示线程阶段，时间，发送字节数，接受字节数，虚拟主机以及请求的表。列出了所有的线程。

6 使用JMX代理Servlet

6.1 简介

JMX代理Servlet是一款轻量级代理。
用来获取和设置信息。

6.2 JMX查询命令

JMX查询的命令格式：

http://webserver/manager/jmxproxy/?qry=STUFF

STUFF是要执行的JMX查询，例如：

• qry=*%3Atype%3DRequestProcessor%2C* --> type=RequestProcessor which will locate all workers which can process requests and report their state.
  定位所有能够处理的请求并汇报各自状态。
• qry=*%3Aj2eeType=Servlet%2c* --> j2eeType=Servlet which return all loaded servlets.
  查询返回所有加载的Servlet。
• qry=Catalina%3Atype%3DEnvironment%2Cresourcetype%3DGlobal%2Cname%3DsimpleValue --> Catalina:type=Environment,resourcetype=Global,name=simpleValue which look for a specific MBean by the given name.
  按照指定名称查找M Bean。

6.3 JMX的get命令

通过get命令获取特性MBean的属性值：

http://webserver/manager/jmxproxy/?get=BEANNAME&att=MYATTRIBUTE&key=MYKEY

必须提供以下参数：

1. get：M Bean的完整名称。
2. att：希望获取的属性。
3. key：（可选参数）CompositeData M Bean的属性中的键。

6.4 JMX的set命令

http://webserver/manager/jmxproxy/?set=BEANNAME&att=MYATTRIBUTE&val=NEWVALUE

必须提供以下参数：

1. set：完成的bean值。
2. attr：想要改变的属性。
3. val：新的属性值

6.5 JMX的invoke命令

通过invoke命令，可以在M Bean中调用方法：

http://webserver/manager/jmxproxy/?invoke=BEANNAME&op=METHODNAME&ps=COMMASEPARATEDPARAMETERS

例如，使用如下方法调用Service的findConnector()方法：

http://localhost:8080/manager/jmxproxy/?invoke=Catalina%3Atype%3DService&op=findConnectors&ps=

7 利用Ant执行Manager的命令

Tomcat为Ant构建工具准备了一套方便的任务定义，使用这些命令需要执行以下操作：

• Download the binary distribution of Ant from http://ant.apache.org. You must use version 1.4 or later.
• Install the Ant distribution in a convenient directory (called ANT_HOME in the remainder of these instructions).
• Add the $ANT_HOME/bin directory to your PATH environment variable.
• Configure at least one username/password combination in your Tomcat user database that includes the manager-script role.

。。。