plugin-cfg.xml 文件
plugin-cfg.xml 文件中包含用于确定 Web 服务器插件如何转发请求的配置信息。
WebSphere Application Server(传统)
您可以创建两种类型的 plugin-cfg.xml 文件:以应用程序为中心和以拓扑为中心。

以应用程序为中心的配置文件具有一个同时映射到 Web 服务器定义和应用程序服务器定义的应用程序。通过使用管理控制台对插件所做的更改在生成时,会持久保存到 plugin-cfg.xml 文件中。以应用程序为中心的配置为动态功能(例如,智能管理)提供了增强的灵活性和支持。
以拓扑为中心的文件代表环境中所定义的一切。通常,当您未定义 Web 服务器时,会使用此 plugin-cfg.xml 文件。
- 如果 app_server_root\dmgr\cells 目录中存在 plugin-cfg.xml 文件,那么插件生成过程会忽略管理控制台 面板中的更新值,并使用该 XML 文件中的现有值。在这种情况下,您必须手动更新该 XML 文件以持久保存那些值。
- 如果 app_server_root\dmgr\cells 目录中不存在 plugin-cfg.xml 文件,那么插件生成过程会创建 plugin-cfg.xml 文件。该过程将持久保存管理控制台中 面板上设置的最新值。


Liberty
您可以通过从与您的服务器相同的 Java SDK 中调用 WebSphere:name=com.ibm.ws.jmx.mbeans.generatePluginConfig MBean 来为 Liberty 服务器生成 plugin-cfg.xml 文件。
元素和属性
plugin-cfg.xml 文件包括以下元素和属性。除非另行指示,否则您在 plugin-cfg.xml 文件内只能指定每一个元素和属性一次Config 元素为必需元素。
- Config
- IgnoreDNSFailures
- RefreshInterval
- ASDisableNagle
IISDisableNagle
- VHostMatchingCompat
- AppServerPortPreference
- ResponseChunkSize
- AcceptAllContent
- ChunkedResponse
- ESIEnableToPassCookies
- GetDWLMTable
OS400ConvertQueryStringToJobCCSID
- 日志
- Property Name=“esiEnable” Value=“true/false”
- Property Name=“esiMaxCacheSize” Value=“integer”
- Property Name=“ESIInvalidationMonitor” Value=“true/false”
- Property Name=“FIPSEnable” Value=“true/false”
- Property Name=“PluginInstallRoot” Value=“C:\IBM\WebSphere\Plugins”
- ServerCluster
- VirtualHostGroup
- UriGroup
- Route
- RequestMetrics
Config
此元素为必需元素,会启动 HTTP 插件配置文件。
IgnoreDNSFailures
指定启动时插件是否忽略配置中的 DNS 故障。当设置为 true 时,如果每个服务器集群中至少有一个服务器能够解析主机名,那么插件会忽略配置中的 DNS 故障并成功启动。无法解析其主机名的所有服务器在配置生存期内均被标记为“不可用”。路由请求期间不会再尝试解析此主机名。如果发生 DNS 故障,日志消息会写入插件日志文件,并且插件初始化会继续进行而不会导致 Web 服务器不启动。缺省值为 false,这表示 DNS 故障会导致 Web 服务器不启动。
RefreshInterval
指定插件检查配置文件以查看是否发生更新或更改的时间间隔(以秒计)。插件检查文件自上次装入插件配置以来,是否有任何修改。
ASDisableNagle
指定用户是否要对插件和应用程序服务器之间的连接禁用 nagle 算法。缺省情况下,会启用 nagle 算法。
值可以为 true 或 false。
![[Windows]](../images/windows.gif)
IISDisableNagle
指定用户是否要在 Microsoft Internet Information Services (IIS) 上禁用 nagle 算法。缺省情况下,会启用 nagle 算法。
值可以为 true 或 false。
VHostMatchingCompat
- true(如果是通过使用接收请求的端口号完成的物理匹配)。
- false(如果是通过使用主机头中包括的端口号完成的逻辑匹配)。
缺省值为 false。
AppServerPortPreference
- hostHeader(如果要使用入局 HTTP 请求的主机头的端口号)。
- webserverPort(如果要使用 Web 服务器用于接收请求的端口号)。
缺省值为 hostHeader。
ResponseChunkSize
指定读取响应主体时使用的最大区块大小。例如,指定 Config ResponseChunkSize=“N”>,其中 N 等于区块大小(以千字节计)。
插件读取响应主体(以 64K 区块计),直到读取所有的响应数据。此方法会导致包含大量数据的响应主体请求的性能问题。
如果响应主体的内容长度未知,那么会分配大小为 N KB 的缓冲区,并且会以 N KB 大小的区块读取主体,直到读完整个主体为止。如果内容长度已知,那么会使用内容长度的缓冲区大小或 N((哪一个较小就用哪一个)来读取响应主体。
缺省区块大小是 64K。
AcceptAllContent
- True(如果内容为所有请求所期望及读取)
- False(如果内容仅为 POST 和 PUT 请求所期望及读取)
缺省值为 True。
ChunkedResponse
指定当响应中出现“Transfer-Encoding : Chunked”响应头时,插件是否必须将发送到客户机的响应分块。
此属性只适用于 IIS、Oracle iPlanet 和 Lotus® Domino® Web 服务器。IBM® HTTP Server 自动处理是否将对客户机的响应进行分块。
您可以为此属性指定下列某个值:
- true(当响应中出现“Transfer-Encoding : Chunked”响应头时,如果插件将发送到客户机的响应分块)。
- 如果不要将该响应分块,那么指定 false。
缺省值为 false。
ESIEnableToPassCookies
指定在处理 ESI 包含请求时,是否允许将会话 cookie 转发到 WebSphere Application Server。如果此值设置为 true,那么会启用此定制属性。如果此值设置为 false,那么会禁用此定制属性。缺省情况下,此值设置为 false。
GetDWLMTable
指定在处理任何 HTTP 请求之前,是否允许新创建的插件进程主动从 WebSphere Application Server 请求分区表。仅当配置了内存到内存会话管理时,才会使用此定制属性。如果此值设置为 true,那么会启用此定制属性。如果此值设置为 false,那么会禁用此定制属性。缺省情况下,此值设置为 false。
![[IBM i]](../images/iseries.gif)
OS400ConvertQueryStringToJobCCSID
指定 HTTP 请求的查询字符串是否会转换为 IBM HTTP Server 作业的代码页或 EBCDIC 代码页 37 以便进行内部处理。缺省值是 false,这会导致查询字符串转换为 EBCDIC 代码页 37。
TrustedProxyEnable
允许此 Web 服务器插件与针对 TrustedProxyList 定制属性列出的代理服务器和负载均衡器连接。当此属性设置为 true 时,此受信代理列表中的代理服务器和负载均衡器可以设置 $WSRA 和 $WSRH 内部头的值。$WSRA 内部头是远程主机(通常是浏览器)的 IP 地址,或由网络地址转换 (N.A.T) 所获取的内部地址. $WSRH 内部头是远程主机的主机名。此头信息使 Web 服务器插件能够与该特定代理服务器或负载均衡器连接。
使用此定制属性时,您还必须使用 TrustedProxyList 定制属性来指定受信代理服务器和负载均衡器的列表。另外,您必须取消选中管理控制台中“请求路由”面板上的“移除特殊头”复选框。有关更多信息,请参阅有关 Web 服务器插件请求路由属性的文档。
TrustedProxyList
指定有权与此 Web 服务器插件连接的所有代理服务器或负载均衡器的逗号分隔列表。此属性必须与 TrustedProxyEnable=true 定制属性设置配合使用。如果将 TrustedProxyEnable 定制属性设置为 false,那么会忽略此列表。
SSLConsolidate
指定 Web 服务器插件是否要将每个新 SSL 传输的设置,与配置文件中已定义的其他 SSL 传输的设置相比较。如果将此属性设置为 true,且插件确定针对新 SSL 传输指定的密钥环和 CertLabel 值,与针对已定义 SSL 传输指定的值相匹配,那么插件会使用现有 SSL 环境,而不是创建新的 SSL 环境。创建较少的 SSL 环境意味着插件需要较少的内存,并且插件初始化时间减少,从而优化整体的 GSkit 环境。
![[AIX Solaris HP-UX Linux Windows]](../images/dist.gif)
SSLPKCSDriver
指定与可选 SSL 协处理器连接的可装入模块的标准名称。标准名称必须包含目录路径和模块名。
![[AIX Solaris HP-UX Linux Windows]](../images/dist.gif)
SSLPKCSPassword
指定模块(针对 SSLPKCSDriver 定制属性指定)所连接的 SSL 协处理器的密码。
如果使用的是 IBM HTTP Server,那么可以使用 sslstash 程序来创建包含此密码的文件。在这种情况下,您可以指定该文件的标准名称(而不是实际密码)作为此定制属性的值。
日志
描述由插件写入的日志消息的位置和级别。如果配置文件中未指定日志元素,那么在某些情况下,日志消息将被写入到 Web 服务器错误日志中。
例如,您可以指定以下代码行:
![[AIX Solaris HP-UX Linux Windows]](../images/dist.gif)
![[IBM i]](../images/iseries.gif)
<Log LogLevel=“Error” Name=“/opt/WebSphere/AppServer60/logs/http_plugin.log”/>
![[z/OS]](../images/ngzos.gif)
<Log LogLevel=“Error” Name=“/log_directory/file_name”/>
- Name
插件将错误消息写入到的日志文件的标准路径。为每个日志指定一个属性。
如果文件不存在,那么系统会创建一个。如果文件存在,那么将以附加模式打开它,并且会保留先前的插件日志消息。
对于转换用户: 从 V7 开始,不再向您为插件日志文件指定的名称追加日期与时间戳记以及进程标识。因此,将创建单个 Web 服务器插件日志文件,而不是创建按日期区分的多个日志文件。trns
- LogLevel
指定插件向日志写入的日志消息的详细级别。为每个日志指定零个或一个下列值:
日志级别值 日志级别描述 跟踪 详细记录请求过程中的所有步骤。 统计信息 记录了为每个请求选择的服务器和其他与请求处理相关的负载均衡信息。 警告 记录所有来自异常请求处理的警告和错误消息 错误 仅记录异常请求处理产生的错误消息 调试 记录处理请求时执行的所有关键步骤。 详细信息 记录关于请求和响应的所有信息。 如果未对“日志”元素指定值 LogLevel,那么会使用缺省值“错误”。
避免故障: 将级别设置为“跟踪”时,请小心。此级别会记录多条消息,因此可能快速耗用磁盘空间。不要在正常运行的环境中使用“跟踪”设置,因为它会对性能造成负面影响。gotcha
避免故障: 将级别设为“跟踪”时,请小心。此级别会记录多条消息,因此可能快速耗用文件系统。不要在正常运行的环境中使用“跟踪”设置,因为它会对性能造成负面影响。gotcha
Property Name=“esiEnable” Value=“true/false”
启用或禁用 Edge Side Include (ESI) 处理器。如果 ESI 处理器和于禁用状态,那么将忽略此文件中的其他 ESI 元素。
可以将 Value 设置为 true 或 false。缺省情况下,ESI 处理器处于禁用状态,其值设置为 false。
Property Name=“esiMaxCacheSize” Value=“integer”
指定高速缓存的最大大小(以 1 KB 为单位)。高速缓存的缺省最大大小为 1024 KB(也就是 1 MB)。如果高速缓存已满,那么要从高速缓存删除的第一个条目是最接近其截止时间的条目。
Property Name=“ESIInvalidationMonitor” Value=“true/false”
指定 ESI 处理器是否从应用程序服务器接收失效信息。
可以将 Value 设置为 true 或 false。缺省情况下,此属性设置为 false。
Property Name=“FIPSEnable” Value=“true/false”
指定是否启用联合信息处理标准 (FIPS) 来建立与应用程序服务器的安全套接字层 (SSL) 连接。如果应用程序服务器上启用了 FIPS,那么将此属性设置为 true。
可以将值 Value 设置为 true 或 false。缺省情况下,此属性设置为 false。
Property Name=“PluginInstallRoot” Value=“C:\IBM\WebSphere\Plugins”
指定插件的安装路径。如果使用的是全局安全性工具箱 (GSKit),那么此属性为必填属性,因为 WebSphere Application Server 支持本地安装而不是全局安装的 GSKit。此属性值设置为插件安装根目录的标准路径。
传输可识别的受支持名称为 keyring、stashfile 和 password。缺省情况下,此属性设置为 none。
ServerCluster
指定通常配置为对同一类型的请求提供服务的一组服务器。为每个配置指定一个或多个集群。
最简单的情况是集群仅包含一个服务器定义。在定义了多个服务器的情况下,插件将使用轮询或随机算法将负载均衡地分布到所定义的服务器上。缺省算法是轮询。
以下代码是 ServerCluster 元素的示例:
![[AIX Solaris HP-UX Linux Windows]](../images/dist.gif)
![[IBM i]](../images/iseries.gif)
<ServerCluster Name=“Servers”>
<ClusterAddress Name=“ClusterAddr”>
<Transport Hostname=“192.168.1.2” Port=“9080” Protocol=“HTTP”/>
<Transport Hostname=“192.168.1.2” Port=“9443” Protocol=“HTTPS”>
<Property Name=“Keyring” value=“c:/WebSphere/AppServer/keys/keyring.kdb”/>
<Property Name=“Stashfile” value=“c:/WebSphere/AppServer/keys/keyring.sth”/>
</Transport>
</ClusterAddress>
<Server Name=“Server1”>
<Transport Hostname=“192.168.1.3” Port=“9080” Protocol=“HTTP”/>
<Transport Hostname=“192.168.1.3” Port=“9443” Protocol=“HTTPS”>
<Property Name=“Keyring” value=“c:/WebSphere/AppServer/keys/keyring.kdb”/>
<Property Name=“Stashfile” value=“c:/WebSphere/AppServer/keys/keyring.sth”/>
</Transport>
</Server>
<Server Name=Server2>
<Transport Hostname=“192.168.1.4” Port=“9080” Protocol=“HTTP”/>
<Transport Hostname=“192.168.1.4” Port=“9443” Protocol=“HTTPS”>
<Property Name=“Keyring” value=“c:/WebSphere/AppServer/keys/keyring.kdb”/>
<Property Name=“Stashfile” value=“c:/WebSphere/AppServer/keys/keyring.sth”/>
</Transport>
</Server>
<Server Name=“Server3”>
<Transport Hostname=“192.168.1.5” Port=“9080” Protocol=“HTTP”/>
<Transport Hostname=“192.168.1.5” Port=“9443” Protocol=“HTTPS”>
<Property Name=“Keyring” value=“c:/WebSphere/AppServer/keys/keyring.kdb”/>
<Property Name=“Stashfile” value=“c:/WebSphere/AppServer/keys/keyring.sth”/>
</Transport>
</Server>
<PrimaryServers>
<Server Name=“Server1”/>
<Server Name=“Server2”/>
</PrimaryServers>
<BackupServers>
<Server Name=“Server3”/>
</BackupServers>
</ServerCluster>
![[z/OS]](../images/ngzos.gif)
<ServerCluster CloneSeparatorChange=“false”
LoadBalance=“Round Robin” Name=“Cluster1”
PostSizeLimit=“10000000” RemoveSpecialHeaders=“true”
RetryInterval=“60”>
<Server
CloneID=“BA36BEC1EB243D8B000000E4000000030926301B”
ConnectTimeout=“0” ExtendedHandshake=“false”
LoadBalanceWeight=“2” MaxConnections=“0”
Name=“SY1_ClusterMember1” WaitForContinue=“false”>
<Transport Hostname=“BOSSXXXX.PLEX1.L2.IBM.COM” Port=“9084” Protocol=“http”/>
<Transport Hostname=“BOSSXXXX.PLEX1.L2.IBM.COM” Port=“0” Protocol=“https”>
<Property Name=“Keyring” value=“safkeyring:///mzjring1/”/>
<Property Name=“Stashfile” value=“”“”/>
<Property Name=“certLabel” Value=“selfsigned”/>
</Transport>
</Server>
<Server CloneID=“BA36BED017FDF40E000000E4000000030926301B”
ConnectTimeout=“0” ExtendedHandshake=“false”
LoadBalanceWeight=“2” MaxConnections=“0”
Name=“SY1_ClusterMember2” WaitForContinue=“false”>
<Transport Hostname=“BOSSXXXX.PLEX1.L2.IBM.COM” Port=“9085” Protocol=“http”/>
<Transport Hostname=“BOSSXXXX.PLEX1.L2.IBM.COM” Port=“0” Protocol=“https”>
<Property Name=“Keyring” value=“safkeyring:///mzjring1/”>
<Property Name=“Stashfile” value=“”“”/>
<Property Name=“certLabel” Value=“selfsigned”/>
</Transport>
</Server>
<PrimaryServers>
<Server Name=“SY1_ClusterMember1”/>
<Server Name=“SY1_ClusterMember2”/>
</PrimaryServers>
</ServerCluster>

z/OS PTF UK35083 包中包括了对 z/OS HTTP Server V5.3 的 SSL 接口更改,该更改与此 Web 服务器插件更改相对应。因此,必须将此 PTF 应用于系统,新的 Web 服务器插件 SSL 接口才能正常工作。
对于 IBM HTTP Server for z/OS V5.3,您还必须在 httpd.conf 中包括 SSLMODE=MULTI 选项。在 V7.0 或更高版本中不支持 SSLMODE=ON 选项。
如果未在 httpd.conf 文件中指定 SSLMode multi 选项,或者未将 z/OS PTF UK35083 包应用于系统,那么可能会接收到错误消息 IMW0584W。该错误消息指示为 HTTP Server 指定的 SSL 模式与为 Web 服务器插件(与 IBM HTTP Server for z/OS V5.3 配合使用)的 SSL 模式不兼容。在任何一种这样的情况下,都可能会发生不可预测的结果。
- 如果您将 kdb 文件与分层文件系统 (HFS) 中的存储文件配合使用,请同时指定 Property Name=keyring 和 Property Name=stashfile 元素,如前面示例中所示。
避免故障: 为这些元素指定的值的格式与产品先前版本中指定的格式不同。gotcha
- 如果使用系统授权工具 (SAF) 密钥环而不使用 kdb 文件,那么必须在管理控制台中创建以下两个定制插件属性:
- KeyringLocation
- 将 SAF 密钥环的目录位置指定为此属性的值。保存此配置更改之后,该目录位置会成为 plugin-cfg.xml 文件中 keyring 属性的值。
- StashfileLocation
- 将 “”“”(空)指定为此属性的值。保存此配置更改之后,“”“”(空)会成为 plugin-cfg.xml 文件中 stashfile 属性的值。
有关如何在管理控制台中创建 KeyringLocation 和 StashfileLocation 的指示信息,请参阅Web 服务器插件配置属性。
对 SAF 密钥环使用下列示例:<Transport Hostname=“appserver.example.com” Port=“9443” Protocol=“https”> <Property name=“keyring” value=“safkeyring:///SAF_keyring_name”/> <Property Name=“stashfile” value=“”“”/> </Transport>
- Name
指定将用于此组服务器的逻辑名或管理名。为每个 ServerCluster 指定一个属性。
- LoadBalance
可以为此属性指定以下值:
循环法
随机
循环法实现具有随机起始点。第一个应用程序服务器是随机检取的。循环法然后用于从该点转发检取应用程序服务器。此实施确保在基于多进程的 Web 服务器中,将第一个请求发送到同一服务器时不会启动所有进程。
随机实施也具有随机起始点。但是,对于此实施,所有后续服务器也是随机选择的。因此,可能重复选择了同一服务器,而其他服务器则保持空闲状态。
缺省负载均衡类型是循环法。
- IgnoreAffinityRequests
指定在基于轮询算法选择服务器时,插件是否应忽略向服务器作出的亲缘关系请求的数目。为每个 ServerCluster 指定零个或一个属性。值为 true 或 false。如果此值设置为 false,那么在服务器选择过程中还将考虑亲缘关系请求的数目。
缺省值为 false,这意味着在轮询算法中将使用所作的亲缘关系请求的数目。
对于转换用户: 对于过渡用户:这是对产品先前版本的更改。在旧版本的 WebSphere Application Server 中,缺省值为 true。trns
- RetryInterval
指定整数值的时间长度,这段时间应该是从将服务器标记为当机到插件重试连接之间的时间。缺省值为 60 秒。为每个 ServerCluster 指定零个或一个属性。
- RemoveSpecialHeaders
在将请求转发到应用程序服务器之前,插件将一些特殊的头添加到请求。这些头存储有关应用程序使用的请求的信息。缺省情况下,插件在添加所需添加的头时,会从入局请求中移除这些头。为每个 ServerCluster 指定零个或一个属性。
值可以为 true 或 false。如果将该属性设置为 false,那么不会移除入局请求中的头,这是一个潜在的安全性漏洞。
- CloneSeparatorChange
指示插件希望将加号 (+) 作为克隆分隔符。某些普及型设备无法处理冒号字符(:),该字符用于分隔与会话亲缘关系联合的克隆标识。您必须更改应用程序服务器配置,以便应用程序服务器也使用加号来分隔克隆标识。为每个 ServerCluster 指定零个或一个属性。
值可以为 true 或 false。
- PostSizeLimit
插件尝试将请求发送到应用程序服务器时,所允许的请求内容分块的最大 KB(1024 字节)数。如果接收到大于此大小的请求,那么插件不会发送该请求。缺省值为 -1 字节,指示发布大小没有限制。为每个 ServerCluster 指定零个或一个属性。
- PostBufferSize
指定读取 HTTP 请求内容时使用的最大缓冲区大小(以 KB 计)。如果最初接收到请求的应用程序服务器无法处理该请求,那么将此缓冲区中包含的数据会发送到另一个应用程序服务器。然后,它尝试让该应用程序服务器处理此请求。如果您不想要具有要缓冲的内容的请求,那么可以将此选项设置为 0,然后重试。
此选项改进了插件的可用性。当此选项设置为非零值时,如果所选应用程序服务器未响应,那么会再次发送包含有效内容的暂挂包。
通常,POST 和 PUT 请求包含有效内容,但其他请求可能也包含有效内容。即使 POST 或 PUT 请求没有有效内容,如果为此选项指定了非零值,也会重试请求。
缺省值为 0。为每个 ServerCluster 指定零个或一个属性。
- ServerIOTimeoutRetry
指定 HTTP 插件重试已超时(由于 ServerIOTimeout)的 HTTP 请求的次数限制。缺省值 -1 指示对重试次数不应用任何其他限制。0 值指示不重试。重试次数总是受集群中的可用服务器数限制。
要点: 此伪指令不适用于由于 HTTP 插件的 ConnectTimeout 设置而导致的连接失败或超时。 - Server指定根据插件配置的路由规则配置为处理路由到其中的请求的 WebSphere Application Server 实例。该服务器对应于在本地机器或远程机器上运行的应用程序服务器。为每个 ServerCluster 指定零个或一个属性。
- Name
指定服务器的管理名或逻辑名。为每个 Server 指定一个属性。
- CloneID
如果请求的 HTTP cookie 头或 URL(如果使用 URL 重写的话)中包含此唯一标识,那么只要符合所有其他路由规则,插件就会将该请求路由到此特定服务器。如果在服务器中未指定 CloneID,那么不会对此服务器启用会话亲缘关系。可以为每个 Server 指定零个或一个属性。
此属性与会话亲缘关系配合使用。当设置了此属性时,插件检查入局 cookie 头或 URL 中是否有 JSESSIONID。如果找到了 JSESSIONID,那么插件会查找一个或多个克隆标识。如果找到了克隆标识,并使它与为此属性指定的值相匹配,那么会将请求发送到此服务器而不是在集群中保持负载均衡。
最佳实践: 如果您不打算使用会话亲缘关系,那么从配置中移除这些克隆标识,因为设置这些标识会增加插件处理请求时的负载。如果插件中没有克隆标识,那么假定会话亲缘关系未启用,并且请求在集群中保持负载均衡。bprac
- WaitForContinue
指定在将请求内容发送到应用程序服务器之前,是否要使用 HTTP 1.1 100 Continue 支持。可能的属性值为 true 或 false。缺省值为 false;插件在发送请求内容之前,不会等待来自应用程序服务器的 100 Continue 响应,因为这会降低性能。为每个 Server 指定零个或一个属性。
对于 POST 请求会忽略此属性,以防止当应用程序服务器由于保持活动超时而关闭连接时发生故障。
将插件配置为与特定类型的代理防火墙配合使用时,将此功能启用为 true。
- LoadBalanceWeight
指定当插件执行加权轮询负载均衡时,与此服务器相关联的权重。为每个 Server 指定零个或一个属性。服务器的开始值可以为 0 和 20 之间的任何整数。但是,只对未在运行的服务器指定 0。
每个服务器的 LoadBalanceWeight 值对于该服务器所处理的每个请求是递减的。在服务器集群中特定服务器的权重达到零之后,只会将具有会话亲缘关系的请求传递到该服务器。当集群中的所有服务器都达到权重 0 时,集群中所有服务器的权重都会重置,然后算法重新启动。
最佳实践: 当某个服务器未在运行时,将该服务器的权重设置为 0。然后插件可以复位仍在运行的服务器的权重,并维持适当的负载均衡。bprac
- ConnectTimeout
使插件可以执行与应用程序服务器的非阻塞式连接。当插件无法联系目标以确定端口是否可用时,非阻塞式连接是有益的。为每个 Server 指定零个或一个属性。
如果未指定 ConnectTimeout 值或此值设置为 0,那么插件将执行阻塞式连接,在这种连接中,插件会一直等待,直到操作系统超时(长度为 2 分钟,具体取决于平台)并允许插件将服务器标记为不可用。值 0 导致插件执行阻塞式连接。大 于 0 的值指定您要插件等待成功连接的秒数。如果未能在此时间间隔内建立连接,那么插件将把此服务器标记为不可用,并故障转移到集群中定义的其他服务器中的一个服务器。
缺省值为 5。
- ExtendedHandshake
当代理防火墙在插件和应用程序服务器之间时,使用此参数。在这种情况下,插件不会像期望的那样执行故障转移。为每个 Server 指定零个或一个属性。
当 connect() 方法失败时,插件将服务器标记为当机。但是,当代理防火墙在插件和应用程序服务器之间时,即使后端应用程序服务器已当机,connect() 方法也会成功。这导致插件没有正确地故障转移到其他应用程序服务器。
插件与应用程序服务器执行某些握手以确保它在发送请求前已启动。此方案使插件能够在应用程序服务器当机时执行故障转移。
值可以为 true 或 false。
- MaxConnections
指定可以及时流经任何点上的 Web 服务器进程的应用程序服务器的最大暂挂连接数。为每个服务器指定一个属性。
例如,在下列方案中:- 此应用程序服务器前面有五个正在运行 IBM HTTP Server 的节点。
- 每个节点启动两个进程。
- MaxConnections 属性设置为 50。
在此示例中,应用程序服务器可以潜在地获取最多 500 个连接。用节点数 5 乘以进程数 2,然后将得数乘以为 MaxConnections 属性指定的数字 50,得到总数 500 个连接。
此属性在 z/OS 操作系统上不事必需属性。z/OS 控制器与工作负载管理器 (WLM) 共同动态地处理新连接。
缺省情况下,MaxConnections 设置为 -1。如果此属性设置为 0 或 -1,那么与应用程序服务器的暂挂连接数没有限制。
- Transport
指定用于对特定 WebSphere Application Server 实例的读取和写入请求的传输。传输提供一些信息,需要这些信息来确定请求发送到的应用程序服务器的位置。如果将多个传输定义为使用同一协议,那么插件将无法识别传输。无法预测插件所选择的传输。插件始终选取在处理过程中遇到的第一个传输。为每个 Server 指定一个或多个元素。
可以将服务器配置为具有一个非安全传输和一个使用 SSL 的传输。在此配置中,会执行入局请求协议匹配来确定用来将请求发送到应用程序服务器的适当传输。
- Hostname
指定 WebSphere Application Server 实例正在其上运行的机器的主机名或 IP 地址。每个传输有且只有一个属性。
- Port
指定 WebSphere Application Server 实例侦听的端口。每个传输有且只有一个属性。
- Protocol
指定当通过此传输进行通信时要使用的协议 -- HTTP 或 HTTPS。每个传输有且只有一个属性。
- Hostname
- Property为每个传输指定零个、一个或多个元素。当传输协议设置为 HTTPS 时,请使用此元素来提供各种初始化参数,如 password、keyring 和 stashfile。例如,包含这些元素的 plugin-cfg.xml 文件的一部分可能类似于以下代码:
<Transport Hostname=“192.168.1.2” Port=“9443” Protocol=“HTTPS”> <Property Name=“keyring” value=“c:/WebSphere/AppServer/keys/keyring.kdb”/> <Property Name=“stashfile” value=“c:/WebSphere/AppServer/keys/keyring.sth”/> <Property Name=“password” value=“WebAS”/>
- Name
指定正在定义的属性名。传输可识别的受支持名称为 keyring、stashfile 和 password。
为每个属性(Property)指定一个特性(attribute)。避免故障: 可以为 WebSphere HTTP for z/OS 插件指定的唯一名称是 password。如果您指定的是 keyring 和 stashfile,会将其忽略。gotcha
- Value
指定要定义的属性的值。为每个属性(Property)指定一个特性(attribute)。
- Name
- ServerIOTimeout
使插件可设置用于将请求发送至应用程序服务器以及从应用程序服务器读取响应的超时值(以秒计)。
如果将 ServerIOTimeout 属性设置为正值,当出现超时时,与服务器的连接尝试会终止。但是,不会将服务器看作不可用,并且在出现不可用超时的情况下仍会将后续请求发送到服务器。
如果将 ServerIOTimeout 属性设置为负值,那么在出现超时的情况下,服务器被看作不可用,并且在出现超时期间不会将后续请求发送到服务器。
如果未设置 ServerIOTimeout 的值,缺省情况下,插件就会使用分块 I/O 将请求写至应用程序服务器以及从应用程序服务器读取响应,并且不会出现 TCP 连接超时。例如,您可能指定以下设置:
<Server Name=“server1” ServerIOTimeout=300>
在这种情况下,如果应用程序服务器停止对请求进行响应,那么插件会等待 300 秒(5 分钟),然后使 TCP 连接超时。如果将 ServerIOTimeout 属性设置为合理的值,那么插件能够较快地使连接超时,并在可能时将请求传输到另一个应用程序服务器。
在选择此属性的值时,请记住,应用程序服务器处理请求有时可能需要几分钟的时间。将 ServerIOTimeout 属性的值设置得过小可能会导致插件将不正确的服务器错误响应发送到客户机。
缺省值为 900,即 15 分钟。
避免故障: ServerIOTimeout 限制插件对每个单独读取或写操作的返回等待时间。ServerIOTimeout 不表示总体请求的超时。gotcha
有关如何配置 ServerIOTimeout 属性的其他建议,请参阅 IBM Support Web 站点上的 Web 服务器插件配置技术说明。
并非发送至应用程序服务器的所有请求以及从应用程序服务器读取的响应都需要相同的 ServerIOTimeout、ServerIOTimeoutRetry 和 Extended Handshake / 100 Continue 超时规则。并非所有 URL 的行为方式都相同,处理时,可能需要使请求更快地超时,或者对于某个请求,无需使每个服务器都重试。可以指定特定 URL,使其使用修改后的 ServerIOTimeout、ServerIOTimeoutRetry,或为 ExtendedHandshake 或 100-Continue 使用更短的超时。 其他未进行此类修改的 URL 将继续使用 Plugin-cfg.xml 文件中指定的值。
要指定需要此修改超时处理的 URL,请使用 SetEnvIf 伪指令修改 httpd.conf 文件。与 Plugin-cfg.xml 文件中可用的属性类似,websphere-serveriotimeout 和 websphere-serveriotimeoutretry 可以接受相同的值。只能将 WebSphere-shorten-handshake 设置为“1”。这样可以使插件将 ConnectTimeout 值用作 ExtendedHandshake 或 100-Continue 响应的等待时间。例如,SetEnvIf Request_URI "\.jsp$" websphere-serveriotimeout=10 SetEnvIf Request_URI "\.jsp$" websphere-serveriotimeoutretry=-1 SetEnvIf Request_URI "\.jsp$" websphere-shorten-handshake=1
- Name
- wsServerIOTimeout
此属性用于设置暂挂 Web 服务器插件与 WebSocket 应用程序之间的读和写操作的超时值(以秒计)。超过所指定的值时,就会释放由未作出响应的应用程序服务器挂起的资源。
缺省值为 30 秒。
- wsServerIdleTimeout
此属性用于设置 Web 服务器插件与 WebSocket 应用程序之间的连接可以保持空闲的超时值(以秒计)。超过所指定的值时,就会释放由应用程序服务器挂起的资源。
缺省值为 900 秒。
- ClusterAddress
ClusterAddress 类似于 server 元素,您可以在其中像对 server 元素一样指定相同的属性和元素。差别在于,在一个 ServerCluster 中,您只能定义一个 ClusterAddress。当您因为在插件和应用程序服务器之间已具有某种类型的负载均衡器而不希望插件执行任何类型的负载均衡时,请使用 ClusterAddress。
避免故障: 如果您包括 ClusterAddress 标记,那么您必须在该标记上包括 Name 属性。插件使用 Name 属性来使集群地址与正确的主机和端口相关联。如果您未指定 Name 属性,那么插件为集群地址分配对使用相同主机和端口的服务器指定的名称。
gotcha<ClusterAddress Name=“MyClusterAddr”> <Transport Hostname=“192.168.1.2” Port=“9080” Protocol=“HTTP”/> <Transport Hostname=“192.168.1.2” Port=“9443” Protocol=“HTTPS”> </ClusterAddress>
如果接收到未建立亲缘关系的请求,那么插件将它路由到集群地址(如果已定义)。如果已建立亲缘关系,那么插件会完全绕过集群地址而将请求直接路由到克隆。如果没有为服务器集群定义集群地址,那么插件会将负载均衡地分布到主服务器列表中的服务器上。
可以为每个 ServerCluster 指定零个或一个属性。
- PrimaryServers
指定插件要将对此集群的请求路由到的服务器列表。如果未指定主服务器列表,那么插件会将请求路由到为服务器集群定义的服务器。为每个 ServerCluster 指定零个或一个元素。
- BackupServers
指定在主服务器列表中指定的所有服务器都不可用时,将请求发送到的服务器列表。插件不会均衡备份服务器之间的负载,但会按顺序遍历列表,直到遍历完列表中的所有服务器,或直到请求成功发送并且从某台服务器接收到响应为止。为每个 ServerCluster 指定零个或一个元素。
VirtualHostGroup
指定在 HTTP Host 头中指定的一组虚拟主机名。使用此属性将配置为处理相似类型请求的虚拟主机定义组合到一起。
以下示例显示 VirtualHostGroup 元素及相关联的元素和属性:
<VirtualHostGroup Name=“Hosts”>
<VirtualHost Name=“www.x.com”/>
<VirtualHost Name=“www.x.com:443”/>
<VirtualHost Name=“*:8080”/>
<VirtualHost Name=“www.x.com:*”/>
<VirtualHost Name=“*:*”/>
</VirtualHostGroup>
- Name
指定用于此组虚拟主机的逻辑名或管理名。为每个 VirtualHostGroup 指定一个属性。
- VirtualHost
指定用来确定入局请求是否应该由 WebSphere Application Server 进行处理的虚拟机器或实际机器所使用的名称。使用此元素来指定 HTTP Host 头中包含的主机名,需要由应用程序服务器处理的请求必须到达这些主机。您可以指定入局请求将使用的特定主机名和端口,也可以对主机名和/或端口指定星号 (*)。
为每个 VirtualHostGroup 指定一个或多个元素。
- Name
指定与 VirtualHost 中的名称相匹配的 HTTP Host 头名称。为每个 VirtualHost 指定一个属性。
值是主机名或 IP 地址与端口的组合,用冒号隔开。
您可以将插件配置为根据请求的入局 HTTP Host 头和端口将请求路由到应用程序服务器。Name 属性指定这些组合。
可以使用通配符表示此属性。唯一可接受的解决方案是将一个星号 (*) 表示主机名,一个星号表示端口,或使用一个星号表示这两者。用一个星号表示这两者意味着任何请求都将与此规则相匹配。如果定义中未指定端口,那么会使用缺省 HTTP端口 80。
- Name
UriGroup
指定在 HTTP 请求行上指定的一组 URI。同一个应用程序服务器必须能够处理这些 URI。路由会将入局 URI 与组中的 URI 作比较,以确定应用程序服务器是否处理请求。
以下示例显示 UriGroup 元素及相关联的元素和属性:
<UriGroup Name=“Uris”>
<Uri Name=“/servlet/snoop/”>
<Uri Name=“/webapp/*/”>
<Uri Name=“*.jsp/”>
</UriGroup>
- Name
指定此组 URI 的逻辑名或管理名。为每个 UriGroup 指定一个属性。
- Uri
指定由 WebSphere Application Server 提供的资源的虚拟路径。每个 URI 指定需要由应用程序服务器处理的入局 URL。您可以在这些定义中使用通配符。每个 UriGroup 可以具有一个或多个属性。
- Name
指定在 HTTP 请求行中指定的与此 URI 成功匹配的实际字符串。您可以在 URI 定义中使用通配符。您可以 指定将由 WebSphere Application Server 处理的规则,如 *.jsp 或 /Servlet/*。当您汇编应用程序时,如果您指定“启用文件服务”,那么仅会为 Web 应用程序生成一个带有通配符的 URI,而不考虑任何显式 Servlet 映射。如果指定按类名处理 Servlet,那么将生成以下 URI:<Uri Name="Web_application_URI/servlet/*">
每个 URI 有且只有一个属性。
- AffinityCookie
指定插件在尝试确定入站请求是否具有会话亲缘关系时使用的 cookie 的名称。缺省值为 JSESSIONID。
请参阅 CloneID 属性的描述,以了解其他会话亲缘关系信息。
每个 URI 可以具有零个或一个属性。
- AffinityURLIdentifier
指定插件在尝试确定入站请求是否具有在特定克隆的 URL 中指定的亲缘关系时使用的标识名。缺省值为 jsessionid。
请参阅 CloneID 属性的描述,以了解其他会话亲缘关系信息。
每个 URI 可以具有零个或一个属性。
- Name
Route
指定插件确定入局请求是否必须由 WebSphere Application Server 处理时使用的请求路由规则。
路由定义是插件配置的中心元素。它指定根据请求的某些特征插件如何处理请求。路由定义包含其他主要元素:必需的 ServerCluster 以及 VirtualHostGroup 和/或 UriGroup。
通过使用在路由的 VirtualHostGroup 和 UriGroup 中定义的信息,插件确定是否将对 Web 服务器的入局请求发送到此路由中定义的 ServerCluster 元素。
请参阅此元素的下列示例:
<Route VirtualHostGroup=“Hosts” UriGroup=“Uris” ServerCluster=“servers”/>
- VirtualHostGroup
指定在确定路由时使用的一组虚拟主机。将入局主机头和服务器端口进行比较以确定此请求是否由应用程序服务器处理。
可以在路由定义中省略此属性。如果未提供此属性,那么在确定路由的虚拟主机匹配部分期间,每个请求都将匹配。
可以为每个 Route 指定零个或一个属性。
- UriGroup
指定在确定路由时使用的一组 URI。为每个路由选择零组或一组 URI。将请求的入局 URI 和此组中定义的 URI 进行比较以确定此请求是否由应用程序服务器处理。
可以在路由定义中省略此属性。如果未提供此属性,那么在确定路由的 URI 匹配部分期间,每个请求都将匹配。
- ServerCluster
指定接收与路由成功匹配的请求的集群。为每个路由选择一个集群。
集群用于处理此请求。如果 URI 和虚拟主机对于此路由都匹配成功,请求将发送到此集群内定义的某个服务器。
RequestMetrics
用来确定是否启用请求度量值,以及当启用了请求度量值时,如何根据因特网协议 (IP) 和统一资源标识 (URI) 过滤器来过滤请求。
请参阅此元素的下列示例:
<RequestMetrics armEnabled=“false” loggingEnabled=“true”
rmEnabled=“false” traceLevel=“PERF_DEBUG”>
- armEnabled
指定插件中是否启用 ARM 4 代理程序。当它设置为 true 时,会调用 ARM 4 代理程序。
避免故障: 对于 SunOne (iPlanet) Web 服务器,obj.conf 文件中必须包含以下伪指令才能启用 ARM 4 支持:
如果未包含此伪指令,那么永远不会调用 arm_stop 过程。gotchaAddLog fn=“as_term”
为 RequestMetrics 选择零个或一个属性。
- loggingEnabled
指定是否在插件中启用请求度量值记录。当它设置为 true 而 traceLevel 未设置为 NONE 时,将记录请求响应时间和其他请求信息。当它设置为 false 时,那么不会记录请求。loggingEnabled 的值取决于为系统属性 com.ibm.websphere.pmi.reqmetrics.loggingEnabled 指定的值。当未提供此系统属性时,loggingEnable 设置为 true。为 RequestMetrics 恰好指定一个属性。
- rmEnabled
指定是否在插件中启用请求度量值。当它设置为 true 时,插件请求度量值将检查过滤器并在插件日志文件中记录请求跟踪记录。如果请求通过了这些过滤器,那么将执行此操作。当此属性设置为 false 时,会忽略其余的请求度量值属性。为 RequestMetrics 恰好指定一个属性。
- traceLevel
指示当 rmEnabled 属性设置为 true 时记录的信息量。当此属性设置为 NONE 时,不会执行任何请求日志记录。当此属性未设置为 NONE 而 loggingEnabled 设置为 true 时,在执行请求时将记录请求响应时间和其他请求信息。为 RequestMetrics 恰好指定一个属性。
- filters
当 rmEnabled 为 true 时,过滤器控制要跟踪的请求。为 RequestMetrics 指定零个、一个或两个属性。
- enable
当启用为 true 时,那么该类型的过滤器已打开,并且请求必须通过该过滤器。为每个过滤器指定一个属性。
- type
有两种类型的过滤器:SOURCE_IP(例如,客户机 IP 地址)和 URI。对于 SOURCE_IP 过滤器类型,将根据已知的 IP 地址来过滤请求。可以使用星号 (*) 指定 IP 地址的掩码。如果使用星号,那么星号必须总是掩码的最后一个字符,例如,127.0.0.*、127.0.* 和 127*。出于性能原因,模式逐个字符地匹配,直到在过滤器中找到星号、发生不匹配或发现过滤器为完全匹配为止。
对于 URI 过滤器类型,将根据入局 HTTP 请求的 URI 来过滤请求。用于模式匹配的规则与用于匹配 SOURCE_IP 地址过滤器的规则相同。
如果 URI 和客户机 IP 地址过滤器都是活动的,请求度量需要同时匹配两种过滤器类型。如果两者都未启用,那么认为所有请求都匹配。
每个过滤器有且只有一个属性。
- filterValues
指定详细的过滤器信息。为每个过滤器指定一个或多个属性。
- value
为相应的过滤器类型指定过滤器值。此值可能是客户机 IP 地址或 URI。为每个 filterValue 指定一个属性。
- value
- enable