状态工作程序参考

简介

Tomcat 连接器有一种特殊类型的工作程序,即所谓的“状态工作程序”。状态工作程序不会将请求转发到 Tomcat 实例。相反,它允许在运行时检索状态和配置信息,并进一步动态更改许多配置项。这可以通过简单的嵌入式 Web 界面来完成。

当与负载均衡工作程序一起使用时,状态工作程序特别强大。

本文档不解释状态工作程序的 HTML 用户界面。到目前为止,它非常简单,所以直接使用即可。相反,本文档尝试解释状态工作程序不太明显的功能。我们还将全面介绍各种请求参数及其含义,以便你可以在自动化脚本中包含状态工作程序。

状态工作程序的文档从 jk 1.2.20 开始

使用模式

操作

状态工作程序了解以下操作

  • list:列出所有已配置工作程序的配置和运行时信息。输出将首先按全局信息(版本数据)分组,然后是负载均衡信息,然后是 AJP 工作程序信息,最后是图例。对于负载均衡器,将有一个摘要部分,然后是每个成员工作程序的详细信息。对于所有工作程序,我们还包括 URL 映射(转发定义)。
  • show:与 list 相同,但仅显示所选工作程序的数据
  • edit:生成一个表单来编辑所选工作程序的配置数据。有一种特殊类型的“edit”,可以轻松地更改负载均衡器所有成员的一个属性,例如它们的激活状态。
  • 更新:提交在编辑表单中进行的更改。注意:更改不会保留到配置文件中。一旦重新启动 Web 服务器,通过状态工作器进行的所有更改都将丢失!另一方面,状态工作器所做的更改将在运行时应用,而无需重新启动 Web 服务器。
  • 重置:重置工作器的所有运行时统计信息。
  • 恢复:标记负载均衡器中处于错误状态的成员,以便立即恢复。
  • 版本:仅显示 Web 服务器和 JK 软件的版本信息
  • 转储:列出原始工作器配置。注意:转储将仅包含启动期间使用的配置。状态工作器本身的动态管理界面稍后应用的任何更改都不会包含在此转储中。转储操作已在版本 1.2.27 中添加。

输出格式

对于大多数操作,您可以在 4 种输出格式之间进行选择。

  • HTML:通过浏览器交互使用
  • XML:主要用于自动化,当您的脚本环境对 XML 友好时。此格式具有丰富的结构信息,但不能按行工作,因此您真的希望将其与 XML 工具一起使用。
  • 属性:此格式是一种基于行的格式,符合 Java 属性文件的规则。大多数结构信息都包含在分层键中。对于配置性质的信息,该格式应生成与您可以在 workers.properties 中使用的行非常相似的行。它不会生成完整的配置文件!
  • 文本:一种简单的文本输出格式。
“编辑”操作仅对 HTML 输出类型有意义。

用户界面功能

在 HTML 视图中,有一个自动刷新功能,通过 HTML 的元刷新选项实现。一旦您启动自动刷新,UI 将对除编辑、更新和维护之外的所有操作都尊重它。即使您浏览其中一个操作,只要您返回到其他操作之一,自动刷新就会再次启动。

HTML 页面的许多部分都可以最小化,如果您对它们不感兴趣。有一些“隐藏”链接,可以折叠部分信息。该功能适用于以下信息块

  • 图例:不要显示“列表”和“显示”操作中显示的信息的图例
  • URI 映射:不要显示工作器的 URI 映射
  • 负载均衡工作器:不要显示类型为“lb”的工作器
  • AJP 工作器:不要显示类型为 ajp 的工作器
  • 平衡器成员:不要显示有关负载均衡器每个成员的详细信息
  • 负载均衡器配置:不要显示负载均衡器的配置数据
  • 负载均衡器摘要:不显示负载均衡器的状态摘要
  • AJP 配置:不显示 ajp 工作负载均衡器成员的配置数据
最后三个最小化功能已添加到 1.2.27 版本中。

关于 URL 映射和虚拟主机的特别注意事项

注意:从 1.2.26 版本开始,已移除以下限制。

Apache 模块 mod_jk 使用与虚拟主机相关的内部 Apache HTTP 服务器基础设施。其缺点是状态工作程序只能显示其定义的虚拟主机的 URL 映射。它无法访问其他虚拟主机的配置对象。当然,您可以在使用的任何虚拟主机中定义状态工作程序。除 URL 映射之外显示的所有信息都相同,与调用状态工作程序的虚拟主机无关。

日志记录

状态工作程序将以日志级别“info”将对配置所做的更改记录到常规 JK 日志文件中。无效请求将以日志级别“warn”记录。如果您要报告某些错误行为,则“debug”甚至“trace”级别的日志文件内容将非常有用。

配置

基本配置

状态工作程序的基本配置与常规 ajp 工作程序非常相似。您需要为工作程序指定一个名称,以及您要映射到该工作程序的 URL。配置的第一部分在 workers.properties 文件中进行。我们定义了一个名为 mystatus 的类型为 status 的工作程序

worker.list=mystatus
worker.mystatus.type=status
然后,我们定义一个应映射到此工作程序的 URL,即我们用于访问状态工作程序功能的 URL。您可以使用 mod_jk 为所选 Web 服务器支持的任何方法。可能性包括 uriworkermap.properties 中的映射、workers.properties 中的附加 mount 属性,或 Apache HTTP 服务器的 JkMount。以下是 uriworkermap.properties 行的一个示例
/private/admin/mystatus=mystatus
URI 模式区分大小写。

正如您将在以下部分中了解到的,状态工作程序非常强大。您应使用 Web 服务器的常规身份验证和授权方法来保护此 URL。

您还可以通过使用不同的名称和 URL 映射来定义状态工作程序的多个实例。例如,您可能希望单独配置它们,然后允许特定人员组使用它们

输出自定义

workers.properties 条目有一些属性,允许自定义状态工作程序输出的各个方面。

属性 css 可以设置为样式表的 URL

worker.mystatus.css=/private/admin/static/mystatus.css
在编写 HTML 输出时,状态工作程序会包含以下行
<link rel="stylesheet" type="text/css" href="/private/admin/static/mystatus.css" />
mod_jk 版本中不包含示例样式表,默认情况下 css 属性为空,因此页面中不会包含样式表引用。状态工作程序输出页面的 HTML 代码不包含任何类属性。如果您希望提供样式表或改进 HTML 布局,请在 tomcat 开发人员列表中联系我们。

可以通过属性 prefix 自定义属性输出格式。状态工作程序输出的所有属性的名称都将以该前缀开头。默认值为“worker”。

在编写 XML 输出时,几个属性会影响格式。属性 ns 允许设置名称空间前缀,该前缀将用于每个状态工作程序+元素。默认值为“jk:”。将其设置为“-”将禁用名称空间前缀。

使用 xmlns 属性,您可以将前缀映射到名称空间 URL。默认值为 xmlns:jk="https://tomcat.net.cn"。将其设置为“-”将禁用 URL 的输出。

最后,您可以通过属性 doctype 指定 XML 文档类型。指定的字符串将插入到文档开头,紧跟在 xml 头之后。默认情况下为空。

保护访问

我们强烈建议您使用 Web 服务器的内置访问控制功能来控制对您选择的 status worker URL 的访问。尽管如此,状态工作程序的两个配置属性还是有帮助的。属性“read_only”禁用状态工作程序的所有功能,这些功能可用于更改其他工作程序的配置或运行时状态。只读状态工作程序不允许访问编辑、更新、重置或恢复操作。默认值为 false,即读/写。要启用只读,您需要将其设置为 true

您可以配置两个状态工作程序,一个具有只读权限,并提供给较大的管理员组,另一个将以完整功能使用,但仅供少数人使用

worker.list=jk-watch
worker.jk-watch.type=status
worker.jk-watch.read_only=true
worker.jk-watch.mount=/user/status/jk
worker.list=jk-manage
worker.jk-manage.type=status
worker.jk-manage.mount=/admin/status/jk
从 1.2.21 版本开始,用户可以通过 HTML GUI 中的链接将读/写状态工作程序临时切换到只读模式。用户始终可以将其切换回读/写。只有通过“read_only”属性配置为只读的状态工作程序才能完全避免应用任何更改。

您可以使用的另一个属性是 user。默认情况下,此列表为空,这意味着对用户没有限制。您可以将“user”设置为以逗号分隔的用户名称列表。如果您的 Web 服务器配置为随请求发送用户名称,则状态工作程序将检查请求中附加的名称是否包含在其“user”列表中。

用户列表可以分割为“用户”属性的多个出现。

默认情况下,用户名称区分大小写。从版本 1.2.21 开始,您可以将属性 user_case_insensitive 设置为 true。然后,比较将不区分大小写。

服务可用性评级

对于负载均衡工作进程,状态工作进程会显示一些有趣的概述信息。它将负载均衡器的成员分类为“良好”、“差”和“降级”。此功能可以与外部升级程序结合使用。根据您的全局系统设计和操作实践,您的首选分类可能有所不同。

分类基于工作进程的激活状态(活动、禁用或已停止),这是一个纯粹的配置状态,以及运行时状态(正常或错误,可能存在空闲、繁忙、恢复、探测和强制恢复等子状态),它仅取决于运行时情况。

运行时子状态具有以下含义

  • 正常(空闲):此工作进程自上次平衡器维护以来未收到任何请求。默认情况下,平衡器维护每 60 秒运行一次。工作进程应该是正常的,但由于我们一段时间没有使用它,因此我们无法确定。在版本 1.2.24 之前,此状态被称为 N/A。
  • 正常(繁忙):此工作进程的所有连接都用于请求。
  • 错误(恢复):工作进程处于错误状态一段时间,现在标记为恢复。适合此工作进程的下一个请求将使用它。
  • 错误(探测):在将工作进程设置为恢复后,我们收到了适合此工作进程的请求。此请求现在正在使用工作进程。
  • 错误(强制恢复):工作进程处于错误状态,但我们没有备用工作进程,因此我们继续使用它。

默认情况下,状态工作进程将所有成员分组为“良好”,这些成员的激活状态为“活动”,运行时状态不等于“错误”,子状态为空。 “差”组由激活状态为“已停止”或运行时状态为“错误”,子状态为空的成员组成。

不适合这两组的任何工作进程都被视为“降级”。

您可以定义其他规则来将工作进程分组为良好、差和降级。两个属性“良好”和“差”可以通过单字符的逗号分隔列表或点分隔对进行填充。每个字符代表以下可能状态之一的第一个字符:“活动”、“禁用”、“已停止”、“正常”、“空闲”、“繁忙”、“恢复”和“错误”。其他状态“探测”和“强制恢复”始终与“恢复”等效。逗号分隔的条目将与逻辑“或”结合,如果您使用点将配置和运行时状态结合起来。它们与逻辑“和”结合。因此,“良好”的默认值为“a.o,a.i,a.b,a.r”,而“差”的默认值为“e,s”。

状态工作进程首先尝试与“差”定义匹配,如果失败,则尝试与“良好”匹配,最后,如果找不到“差”或“良好”匹配,则选择“降级”。

请求参数

本节旨在帮助您根据 jk 状态管理界面构建自动化脚本。此界面是稳定的,因为我们只希望将来添加更多参数。以前版本的现有参数将保留其原始语义。我们还希望 XML、属性和文本输出格式保持稳定。因此,如果您希望在自动化脚本中解析状态工作器输出,请使用这些格式。

操作

操作由参数 cmd 确定。它可以具有值“list”、“show”、“edit”、“update”、“reset”、“recover”、“version”和“dump”。如果您省略 cmd 参数,将使用默认值“list”。除了“list”、“refresh”、“version”和“dump”之外的所有操作都需要其他参数。

操作“dump”已在版本 1.2.27 中添加。

输出格式

格式由参数 mime 确定。它可以具有值“html”、“xml”、“txt”和“prop”。如果您省略 mime 参数,将使用默认值“html”。操作“edit”(编辑表单)仅对“mime=html”有意义。

工作器选择

对单个工作器进行操作的操作需要一个或两个附加参数来选择此工作器。参数 w 包含工作器列表中工作器的名称。如果操作对负载均衡器的成员(子工作器)进行操作,则参数 w 包含负载均衡器工作器的名称,而附加参数 sw 包含子工作器的名称。

自动刷新

在自动刷新期间,参数 re 包含以秒为单位的刷新间隔。如果您省略此参数,自动刷新将关闭。

隐藏选项

参数 opt 包含已激活选项的位掩码。默认值为 0,因此默认情况下不会激活任何选项。存在以下选项

  • 0x0001:隐藏 lb 工作器的成员
  • 0x0002:隐藏 URL 映射
  • 0x0004:隐藏图例
  • 0x0008:隐藏负载均衡器工作器
  • 0x0010:隐藏 ajp 工作器
  • 0x0020:只允许对读/写状态工作器执行只读操作。
  • 0x0040:隐藏负载均衡器配置
  • 0x0080:隐藏负载均衡器状态摘要
  • 0x0100:隐藏 ajp 和负载均衡器成员工作器的配置
值 0x0040-0x0100 已在版本 1.2.27 中添加。

标准更新操作的数据参数

您可以使用编辑操作,最后单击更新按钮,以更改工作器的设置。但您也可以直接调用更新操作。以下请求参数包含您想要更改的配置信息。首先是负载均衡器工作器的列表

  • vlr:重试次数(数字)
  • vlt:恢复时间(秒)
  • vlee:错误升级时间(秒)
  • vlx:最大回复超时次数(数字)
  • vls:会话粘性(0/f/n/off=关闭,1/t/y/on=开启;不区分大小写)
  • vlf:强制会话粘性(0/f/n/off=关闭,1/t/y/on=开启;不区分大小写)
  • vlm:方法(0/r="请求",1/t="流量",2/b="繁忙",3/s="会话",4/s="下一个";不区分大小写,仅使用第一个字符)
  • vll:锁定(0/o="乐观",1/p="悲观";不区分大小写,仅使用第一个字符)
以下是可用于更改负载均衡器成员设置的参数列表
  • vwa:激活标志(0/a="活动",1/d="禁用",2/s="已停止";不区分大小写,仅使用第一个字符)
  • vwf:负载均衡因子(整数权重)
  • vwn:用于会话粘性的路由(字符串)
  • vwr:用于定义简单故障转移规则的重定向(字符串)
  • vwc:用于告知 JK 复制设计的域(字符串)
  • vwd:用于表示首选项的距离(整数)
以下是可用于更改 ajp 工作进程和 ajp 负载均衡器成员设置的参数列表
  • vahst:主机(字符串)
  • vaprt:端口(数字)
  • vacpt:连接池超时(数字)
  • vact:连接超时(数字)
  • vapt:预处理/后处理超时(数字)
  • vart:回复超时(数字)
  • var:重试次数(数字)
  • varo:恢复选项(数字)
  • vabl:繁忙限制(数字)
  • vamps:最大数据包大小(数字)
请注意,更改主机名或端口仅对新连接生效。与旧地址已建立的连接仍将继续使用。尽管如此,此功能仍然很有趣,因为你可以使用端口“0”配置负载均衡器成员,该端口将在启动期间自动停止。稍后,当你了解最终名称和端口时,可以设置它们,它们将自动激活。

前导字符“v”已添加到 1.2.27 版本中的参数。更改 ajp 工作进程的设置也已在 1.2.27 版本中引入。

有关所有参数的详细信息,请参阅workers.properties 参考

负载均衡器成员的 Aspect 编辑

您可以使用编辑操作分别在一个页面上编辑负载均衡器或负载均衡器成员的所有设置。如果您想同时编辑负载均衡器所有成员的一个配置方面,这将由参数 att 触发。该参数的值指示您想要编辑的方面。该列表与前一节中的相同,除了“vahst”和“vaprt”之外:“vwa”、“vwf”、“vwn”、“vwr”、“vwc”、“vwd”、“vacpt”、“vact”、“vapt”、“vart”、“var”、“varo”、“vabl”和“vamps”。但在这里,您需要将名称放入参数 att 中,而不是将其用作请求参数名称。

所有负载均衡器成员的共同方面的值都将在名为“val0”、“val1”....的参数中给出。