web server apache tomcat11-04-manager 如何管理？

前言

整理这个官方翻译的系列，原因是网上大部分的 tomcat 版本比较旧，此版本为 v11 最新的版本。

开源项目

从零手写实现 tomcat minicat 别称【嗅虎】心有猛虎，轻嗅蔷薇。

系列文章

web server apache tomcat11-01-官方文档入门介绍

web server apache tomcat11-02-setup 启动

web server apache tomcat11-03-deploy 如何部署

web server apache tomcat11-04-manager 如何管理？

web server apache tomcat11-06-Host Manager App -- Text Interface

web server apache tomcat11-07-Realm Configuration

web server apache tomcat11-08-JNDI Resources

web server apache tomcat11-09-JNDI Datasource

web server apache tomcat11-10-Class Loader

....

简介

在许多生产环境中，具有能够部署新的 Web 应用程序或取消部署现有应用程序的能力而无需关闭和重新启动整个容器非常有用。

此外，您可以请求现有应用程序重新加载自身，即使您尚未在 Tomcat 服务器配置文件中声明其可重新加载。

为了支持这些功能，Tomcat 包括一个 Web 应用程序（默认安装在上下文路径 /manager），支持以下功能：

功能	描述
从 WAR 文件的上传内容部署新的 Web 应用程序
从服务器文件系统上指定的上下文路径部署新的 Web 应用程序
列出当前部署的 Web 应用程序以及当前为这些 Web 应用程序活动的会话
重新加载现有的 Web 应用程序，以反映 /WEB-INF/classes 或 /WEB-INF/lib 内容的更改
列出操作系统和 JVM 属性值
列出可用的全局 JNDI 资源，供准备嵌套在 部署描述中的 元素的部署工具使用
启动已停止的应用程序（使其再次可用）
停止现有应用程序（使其不可用），但不取消部署它
取消部署已部署的 Web 应用程序并删除其文档基目录（除非它是从文件系统部署的）

默认的 Tomcat 安装包括为默认虚拟主机配置的 Manager 应用程序的实例。

如果您创建了额外的虚拟主机，您可能希望将 Manager 应用程序的实例添加到其中一个或多个主机中。

要将 Manager Web 应用程序上下文的实例添加到新主机上，请在 $CATALINA_BASE/conf/[enginename]/[hostname] 文件夹中安装 manager.xml 上下文配置文件。

以下是一个示例：

<Context privileged="true" antiResourceLocking="false"
         docBase="${catalina.home}/webapps/manager">
  <CookieProcessor className="org.apache.tomcat.util.http.Rfc6265CookieProcessor"
                   sameSiteCookies="strict" />
  <Valve className="org.apache.catalina.valves.RemoteAddrValve"
         allow="127\.\d+\.\d+\.\d+|::1|0:0:0:0:0:0:0:1" />
  <Manager sessionAttributeValueClassNameFilter="java\.lang\.(?:Boolean|Integer|Long|Number|String)|org\.apache\.catalina\.filters\.CsrfPreventionFilter\$LruCache(?:\$1)?|java\.util\.(?:Linked)?HashMap"/>
</Context>

有三种使用 Manager Web 应用程序的方式：

1. 作为带有用户界面的应用程序，您可以在浏览器中使用。以下是一个示例 URL，您可以将 localhost 替换为您的网站主机名：http://localhost:8080/manager/html 。
2. 仅使用 HTTP 请求的最小版本，适用于由系统管理员设置的脚本使用。命令作为请求 URI 的一部分给出，响应以易于解析和处理的简单文本形式呈现。有关更多信息，请参阅支持的 Manager 命令。
3. 适用于 Ant（版本 1.4 或更高版本）构建工具的便捷任务定义集。有关更多信息，请参阅使用 Ant 执行 Manager 命令。

配置 Manager 应用程序访问

以下描述使用变量名 $CATALINA_BASE 来引用相对路径解析的基本目录。

如果您尚未通过设置 CATALINA_BASE 目录来配置 Tomcat 以用于多个实例，则 $CATALINA_BASE 将设置为 $CATALINA_HOME 的值，即您安装 Tomcat 的目录。

使用默认设置将允许互联网上的任何人执行您服务器上的 Manager 应用程序是相当不安全的。

因此，Manager 应用程序附带了这样一个要求：任何试图使用它的人必须进行身份验证，使用具有其中一个 manager-xxx 角色的用户名和密码（角色名称取决于所需的功能）。

此外，默认用户文件（$CATALINA_BASE/conf/tomcat-users.xml）中没有分配给这些角色的用户名。

因此，默认情况下完全禁用了对 Manager 应用程序的访问。

您可以在 Manager Web 应用程序的 web.xml 文件中找到角色名称。可用的角色包括：

• manager-gui — 访问 HTML 界面。
• manager-status — 仅访问 "服务器状态" 页面。
• manager-script — 访问本文档中描述的面向工具友好的纯文本界面，以及 "服务器状态" 页面。
• manager-jmx — 访问 JMX 代理接口和 "服务器状态" 页面。

HTML 界面受到 CSRF（跨站点请求伪造）攻击的保护，但文本和 JMX 界面无法受到保护。这意味着被允许访问文本和 JMX 界面的用户在使用 Web 浏览器访问 Manager 应用程序时必须小心。为了保持 CSRF 保护：

• 如果您使用 Web 浏览器使用具有 manager-script 或 manager-jmx 角色的用户访问 Manager 应用程序（例如用于测试纯文本或 JMX 界面），之后必须关闭所有浏览器窗口以终止会话。如果您不关闭浏览器并访问其他站点，您可能会成为 CSRF 攻击的受害者。
• 建议永远不要将 manager-script 或 manager-jmx 角色授予具有 manager-gui 角色的用户。

请注意，JMX 代理接口实际上是 Tomcat 的类似低级根的管理接口。如果知道要调用的命令，可以做很多事情。启用 manager-jmx 角色时应谨慎。

要启用对 Manager Web 应用程序的访问，您必须创建新的用户名/密码组合并将其中一个 manager-xxx 角色与之关联，或者将 manager-xxx 角色添加到现有用户名/密码组合中。由于本文档的大部分内容都是使用文本界面，因此此示例将使用角色名称 manager-script。用户名/密码的配置方式取决于您正在使用的 Realm 实现：

• UserDatabaseRealm 和 MemoryUserDatabase，或 MemoryRealm — UserDatabaseRealm 和 MemoryUserDatabase 配置在默认的 $CATALINA_BASE/conf/server.xml 中。MemoryUserDatabase 和 MemoryRealm 默认读取位于 $CATALINA_BASE/conf/tomcat-users.xml 的 XML 格式文件，可以使用任何文本编辑器进行编辑。

此文件包含每个个人用户的 XML <user>，可能类似于以下内容：

<user username="craigmcc" password="secret" roles="standard,manager-script" />

它定义了此个人用于登录的用户名和密码，以及他们关联的角色名称。您可以将 manager-script 角色添加到一个或多个现有用户的逗号分隔的角色属性中，并/或创建具有分配了该角色的新用户。

• DataSourceRealm — 您的用户和角色信息存储在通过 JDBC 访问的数据库中。将 manager-script 角色添加到一个或多个现有用户，并/或按照您环境的标准程序创建一个或多个分配了此角色的新用户。

• JNDIRealm — 您的用户和角色信息存储在通过 LDAP 访问的目录服务器中。将 manager-script 角色添加到一个或多个现有用户，并/或按照您环境的标准程序创建一个或多个分配了此角色的新用户。

当您首次尝试发出下一节中描述的 Manager 命令之一时，将要求您使用 BASIC 身份验证登录。您输入的用户名和密码无关紧要，只要它们识别出具有 manager-script 角色的有效用户。

除了密码限制之外，还可以通过添加 RemoteAddrValve 或 RemoteHostValve 来限制对 Manager Web 应用程序的访问。

有关详细信息，请参阅阀门文档。以下是通过 IP 地址限制对 localhost 的访问的示例：

<Context privileged="true">
         <Valve className="org.apache.catalina.valves.RemoteAddrValve"
                allow="127\.0\.0\.1"/>
</Context>

HTML 用户友好界面

Manager Web 应用程序的用户友好的 HTML 界面位于以下位置：

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

如上所述，您需要 manager-gui 角色才能访问它。有一份单独的文档提供了有关此界面的帮助。请参阅：

HTML Manager documentation

HTML 界面受到 CSRF（跨站点请求伪造）攻击的保护。每次访问 HTML 页面都会生成一个随机令牌，该令牌存储在您的会话中，并包含在页面上的所有链接中。如果您的下一个操作没有正确的令牌值，则将拒绝该操作。如果令牌已过期，您可以从 Manager 的主页面或“列出应用程序”页面重新开始。

支持的 Manager 命令

Manager 应用程序知道如何处理的所有命令都在一个单独的请求 URI 中指定，如下所示：

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

其中 {host} 和 {port} 表示 Tomcat 运行的主机名和端口号，{command} 表示您希望执行的 Manager 命令，{parameters} 表示特定于该命令的查询参数。在下面的示例中，根据您的安装情况适当地自定义主机和端口。

这些命令通常由 HTTP GET 请求执行。/deploy 命令有一个通过 HTTP PUT 请求执行的表单。

常见参数

大多数命令接受以下一个或多个查询参数：

• path - 您正在处理的 Web 应用程序的上下文路径（包括前导斜杠）。要选择 ROOT Web 应用程序，请指定“/”。

  注意：不可能对 Manager 应用程序本身执行管理命令。 注意：如果未显式指定路径参数，则将使用标准上下文命名规则从 config 参数或（如果未提供 config 参数）war 参数派生路径和版本。

• version - 此 Web 应用程序的版本，由并行部署功能使用。如果您在需要路径的任何地方使用并行部署，则必须除了路径之外指定一个版本，并且组合路径和版本必须唯一，而不仅仅是路径。

  注意：如果未显式指定路径，则忽略版本参数。

• war - Web 应用程序存档（WAR）文件的 URL，或包含 Web 应用程序的目录的路径名，或包含 Context 配置 ".xml" 文件的路径名。您可以使用以下任何格式的 URL：
  • file:/absolute/path/to/a/directory - 包含 Web 应用程序解压版本的目录的绝对路径。此目录将附加到您指定的上下文路径，而不进行任何更改。
  • file:/absolute/path/to/a/webapp.war - Web 应用程序存档（WAR）文件的绝对路径。这仅适用于 /deploy 命令，并且是该命令唯一可接受的格式。
  • file:/absolute/path/to/a/context.xml - 包含 Context 配置元素的 Web 应用程序上下文配置 ".xml" 文件的绝对路径。
  • directory - Host 的应用程序基目录中的 Web 应用程序上下文的目录名称。
  • webapp.war - Host 的应用程序基目录中位于的 Web 应用程序 WAR 文件的名称。

每个命令将以 text/plain 格式（即不带 HTML 标记的纯 ASCII 文本）返回响应，使人类和程序都可以轻松阅读。

响应的第一行将以 OK 或 FAIL 开头，指示请求的命令是否成功。在失败的情况下，第一行的其余部分将包含遇到的问题的描述。一些命令包括如下所述的其他信息行。

国际化说明 - Manager 应用程序在资源包中查找其消息字符串，因此可能已为您的平台翻译了这些字符串。以下示例显示了消息的英文版本。