第 10 章 使用 Instant Messaging XMPP/HTTP 网关

XMPP/HTTP 网关可让 Instant Messaging 访问不是基于 XMPP 的客户机，例如基于 HTML 的客户机，以及防火墙后的客户机（允许 HTTP 通信，但不允许 XMPP 通信）。网关代表 HTTP 客户机代理到 XMPP 服务器的 Instant Messaging 通信。

使用 Instant Messenger 资源文件将 XMPP/HTTP 网关部署为 Web 容器上的 webapp。

本章中的以下各节提供有关配置和维护 XMPP/HTTP 网关的信息：

• Instant Messaging XMPP/HTTP 网关配置文件

• 配置 Instant Messaging XMPP/HTTP 网关

• 使用 StartTLS 确保 XMPP/HTTP 网关和 Instant Messaging 服务器之间的通信安全

• 管理 XMPP/HTTP 网关的日志记录

Instant Messaging XMPP/HTTP 网关配置文件

XMPP/HTTP 网关使用以下文件进行配置：

• 网关 webapp 配置文件 (web.xml)。此文件的内容决定使用哪个网关配置文件。有关使用非默认配置文件的信息，参见配置 Instant Messaging XMPP/HTTP 网关以使用非默认配置文件。

• 网关配置文件（通常为 httpbind.conf）。有关配置网关的说明，参见配置 Instant Messaging XMPP/HTTP 网关。有关 httpbind.conf 文件语法、文件位置以及此文件中配置参数列表的说明，参见附录 B，httpbind.conf 中的 Instant Messaging XMPP/HTTP 网关配置参数。

• 网关日志记录配置文件（通常为 httpbind_log4j.conf）。有关配置日志记录的详细信息，参见管理 XMPP/HTTP 网关的日志记录。有关日志记录配置文件语法，参见XMPP/HTTP 网关 log4j 日志配置文件语法。

配置 Instant Messaging XMPP/HTTP 网关

当您在安装后运行 configure 实用程序时，可以选择是否部署 XMPP/HTTP 网关。如果启用，则 configure 实用程序会为网关创建一个默认配置文件 (httpbind.conf)。您可以通过修改此文件中的值更改配置。有关 httpbind.conf 文件语法、文件位置以及此文件中配置参数列表的说明，参见附录 B，httpbind.conf 中的 Instant Messaging XMPP/HTTP 网关配置参数，或参阅本节中的说明。

此外，当您选择在初始配置过程中部署网关时，configure 实用程序会在 im-svr-base/work 目录中创建一个 .war 文件，然后在您指定的代码库目录中的 Web 或应用服务器上部署此文件。

您还可以通过修改 web.xml（使用 Web 容器上的客户机资源部署）中的值，来配置网关以使用非默认的配置文件。

在本节的说明中，假定网关配置文件为 httpbind.conf。如果您使用非默认配置文件，请以您的配置文件代替说明中的 httpbind.conf。

每次更改 httpbind.conf 后，都需要重新启动 XMPP/HTTP 网关。

本节包含以下说明：

• 启用或禁用 Instant Messaging XMPP/HTTP 网关

• 配置 XMPP/HTTP 网关处理的并发请求数

• 为 XMPP/HTTP 网关的客户机请求设置 JEP 124 hold 属性

• 指定 XMPP/HTTP 网关允许的客户机非活动时间

• 设置 XMPP/HTTP 网关的 内容类型 HTTP 头

• 设置 XMPP/HTTP 网关的往返时间延迟

• 设置 XMPP/HTTP 网关将发送响应到客户机的默认时间

• 在 Instant Messaging 网关池中配置 XMPP/HTTP 网关

• 为支持的 XMPP/HTTP 网关域配置键 ID 列表

• 配置 Instant Messaging XMPP/HTTP 网关以使用非默认配置文件

有关配置网关日志记录的说明，参见管理 XMPP/HTTP 网关的日志记录。

启用或禁用 Instant Messaging XMPP/HTTP 网关

可通过运行 configure 实用程序，然后设置 iim.conf 中的参数来启用网关。可使用 Web 容器或应用服务器提供的工具稍后禁用网关。

1. 启用网关：

   1. 运行 configure 实用程序。

   2. 当提示时选择部署网关。

      有关详细信息，参见第 1 章，安装后配置 Instant Messaging。

   3. 在 iim.conf 中，将 iim_agent.httpbind.enable 参数设为 true。

      例如：

      iim_agent.httpbind.enable=true

2. 要禁用网关，请使用 Web 或应用服务器提供的工具禁用 webapp。

配置 XMPP/HTTP 网关处理的并发请求数

开始之前

请确保您熟悉 JEP 124 标准草案。有关详细信息，可从 http://www.jabber.org/jeps/jep-0124.html 获得。

1. 打开 httpbind.conf。

   有关查找此文件的信息，参见httpbind.conf 文件位置。

2. 将 httpbind.requests 参数设为单个客户机可向网关发送的最大并发请求数。

   默认值为 2。例如：

   httpbind.requests=2

   客户机可向网关发送的并发请求数。如果此参数的值小于客户机请求中 JEP 124 hold 属性的值，则此参数的值将被设为 hold+1。不要将此参数设为 1，因为这样会严重降低性能。有关 httpbind.hold 参数的详细信息，参见为 XMPP/HTTP 网关的客户机请求设置 JEP 124 hold 属性和表 B–1。

3. 保存并关闭 httpbind.conf。

4. 使用 Web 或应用服务器提供的工具重新启动网关。

为 XMPP/HTTP 网关的客户机请求设置 JEP 124 hold 属性

开始之前

请确保您熟悉 JEP 124 标准草案。有关详细信息，可从 http://www.jabber.org/jeps/jep-0124.html 获得。

1. 打开 httpbind.conf。

   有关查找此文件的信息，参见httpbind.conf 文件位置。

2. 将 httpbind.hold 参数设为您想要网关允许客户机请求中 hold 属性的最大值。

   默认值为 5。例如：

   httpbind.hold=5

   如果客户机发送的 hold 值大于网关的 hold 值，则使用网关的 hold 值。

3. 保存并关闭 httpbind.conf。

4. 使用 Web 或应用服务器提供的工具重新启动网关。

指定 XMPP/HTTP 网关允许的客户机非活动时间

1. 打开 httpbind.conf。

   有关查找此文件的信息，参见httpbind.conf 文件位置。

2. 将 httpbind.inactivity 参数设为您想要网关终止空闲连接所经过的时间（秒）。

   默认值为 180 秒。例如：

   httpbind.inactivity=180

   如果客户机在此时间段内没有轮询网关，则网关会终止该连接。

3. 保存并关闭 httpbind.conf。

4. 使用 Web 或应用服务器提供的工具重新启动网关。

设置 XMPP/HTTP 网关的 内容类型 HTTP 头

1. 打开 httpbind.conf。

   有关查找此文件的信息，参见httpbind.conf 文件位置。

2. 如果客户机在其初始请求中没有指定参数，则应该将 httpbind.content_type 参数设为您希望网关使用的内容类型。

   默认值为 text/xml; charset=utf-8。例如：

   httpbind.content_type=text/xml; charset=utf-8

3. 保存并关闭 httpbind.conf。

4. 使用 Web 或应用服务器提供的工具重新启动网关。

设置 XMPP/HTTP 网关的往返时间延迟

往返时间延迟是您想要允许在网关和客户机之间的往返时间超时之上增加的时间量（秒）。这有助于考虑到网络延迟。

1. 打开 httpbind.conf。

   有关查找此文件的信息，参见httpbind.conf 文件位置。

2. 根据需要设置 httpbind.round_trip_delay 参数。

   将此值设置过高可能会降低性能。该值以秒为单位。默认值为 1 秒。例如：

   httpbind.round_trip_delay=1

   将此值设置过高可能会降低性能。更改此参数前请考虑您的一般网络延迟。

3. 保存并关闭 httpbind.conf。

4. 使用 Web 或应用服务器提供的工具重新启动网关。

设置 XMPP/HTTP 网关将发送响应到客户机的默认时间

1. 打开 httpbind.conf。

   有关查找此文件的信息，参见httpbind.conf 文件位置。

2. 根据需要设置 httpbind.wait_time 参数。

   保证客户机在您指定给此参数的等待时间内会收到来自 XMPP/HTTP 网关的响应。设置此参数时请考虑您的网络速度。不要将该值设置过低，以免 XMPP/HTTP 网关不能及时发送请求。

   该值以秒为单位。默认值为 120 秒。例如：

   httpbind.wait_time=120

   如果为客户机设置的值大于为网关设置的值，则会使用网关等待时间。

3. 保存并关闭 httpbind.conf。

4. 使用 Web 或应用服务器提供的工具重新启动网关。

在 Instant Messaging 网关池中配置 XMPP/HTTP 网关

1. 打开 httpbind.conf。

   有关查找此文件的信息，参见httpbind.conf 文件位置。

2. 将网关配置为带有 Instant Messaging 网关池部署的一部分：

   1. 将 httpbind.pool.support 参数设为 true：

      httpbind.pool.support=true

   2. 将 httpbind.pool.nodeId 参数设为完整的网关 URL。

      该 URL 用作网关的 nodeId，此 nodeId 在服务器池内必须唯一。网关使用此 nodeId 来确定是否必须为收到的请求提供服务，或将请求转发到池中的其他网关。

3. 要将网关配置为不在网关池中工作，请将 httpbind.pool.support 参数设置如下：

   httpbind.pool.support=false

4. 保存并关闭 httpbind.conf。

5. 使用 Web 或应用服务器提供的工具重新启动网关。

为支持的 XMPP/HTTP 网关域配置键 ID 列表

1. 打开 httpbind.conf。

   有关查找此文件的信息，参见httpbind.conf 文件位置。

2. 将 httpbind.config 参数设为您想要网关使用的 ID 列表。

   对于每个域，您都需要为此参数指定一个单独的 ID。例如：

   httpbind.config=gwdomain-id

   其中，gwdomain-id 是您要使用的域标识符。

   例如：

   httpbind.config=siroe.com

3. 对于您要指定的每个 gwdomain-id，请将以下参数添加到 httpbind.conf 文件中：

   gwdomain-id.domain=domain-name gwdomain-id.hosts=gateway-host gwdomain-id.componentjid=component-jid gwdomain-id.password=password

   其中：

   • gwdomain-id 是上一步骤中，在 httpbind.config 中指定的网关 ID。

   • domain-name 是标识的网关在其中运行的域。

   • gateway-host 是全限定域名 (FQDN) 以及支持此域的网关主机端口号列表，以逗号或空格分隔。

   • component-jid 是网关的组件 JID。

   • password 是标识的网关的密码。

   例如，如果 gwdomain-id 设为 siroe：

   siroe.domain=siroe.com siroe.hosts=gateway.siroe.com:5222 siroe.componentjid=http.gateway.siroe.com siroe.password=gatewaypassword

   关于这些关键参数的详细信息，参见httpbind.config 的网关域 ID 键参数。

4. 保存并关闭 httpbind.conf。

5. 使用 Web 或应用服务器提供的工具重新启动网关。

配置 Instant Messaging XMPP/HTTP 网关以使用非默认配置文件

1. 在部署 Instant Messenger 资源文件的 Web 容器上，编辑 web.xml。

   使用 Web 容器的工具编辑此文件。

2. 将 httpbind.config.file 参数的值更改为您想要网关使用的配置文件的位置。

使用 StartTLS 确保 XMPP/HTTP 网关和 Instant Messaging 服务器之间的通信安全

XMPP/HTTP 网关只支持使用 StartTLS 进行安全通信。如果多路复用器配置为使用传统的 SSL，则您需要配置网关，使其绕过多路复用器直接连接到服务器。如果 StartTLS 可用，则网关将始终尝试使用它进行通信。有关详细信息，参见第 12 章，使用 TLS 和传统 SSL 保证 Instant Messaging 的安全性。

管理 XMPP/HTTP 网关的日志记录

您可以配置 XMPP/HTTP 网关的日志记录级别、完全启用或禁用日志记录以及更改网关日志文件或网关日志配置文件的位置，如以下各节所述：

• 启用或禁用 XMPP/HTTP 网关的日志记录

• 更改 XMPP/HTTP 网关日志配置文件的位置

• Linux: 安装或升级后设置 XMPP/HTTP 网关日志文件的位置

• 更改 XMPP/HTTP 网关日志文件的位置

• 使用 XMPP/HTTP 网关的非默认日志文件位置

• 设置 XMPP/HTTP 网关日志记录级别

• XMPP/HTTP 网关 log4j 日志配置文件语法

有关 Instant Messaging 所支持的 log4j 格式的详细信息，参见Apache Logging Services 网站中的相关说明。

启用或禁用 XMPP/HTTP 网关的日志记录

您可以通过两种方式启用或禁用网关的日志记录：

• 添加或删除 httbind.conf 中 httpbind.log4j.config 参数的值。

• （建议使用）修改网关的 log4j 配置文件 (httpbind_log4j.conf) 中的配置。

在大多数情况下，您应该修改 httpbind_log4j.conf 文件本身中的配置，而保留将 httpbind.log4j.config 参数设为 httpbind_log4j.conf 文件的位置。以下过程说明如何修改 httpbind_log4j.conf 文件中的配置。

1. 打开 httpbind_log4j.conf 文件。

   此文件的存储位置是您在 httpbind.conf 文件中指定作为 httpbind.log4j.config 参数的值。默认情况下，文件存储于默认 Instant Messaging 实例的以下目录中：

   im-cfg-base/httpbind_log4j.conf

2. 要禁用网关的日志记录，请将 log4j.logger.gateway 参数设置如下：

   log4j.logger.gateway=OFF

3. 要启用日志记录，请将 log4j.logger.gateway 参数设为所需的日志记录级别。

   例如：

   log4j.logger.gateway=ERROR

   有关您可以使用的有效日志记录级别列表，参见表 13–1。

4. 保存并关闭 httpbind_log4j.conf。

更改 XMPP/HTTP 网关日志配置文件的位置

1. 打开 httpbind.conf。

   有关查找此文件的信息，参见httpbind.conf 文件位置。

2. 将 httpbind.log4j.config 参数的值设为 XMPP/HTTP 网关日志配置文件的位置。

3. 保存并关闭 httpbind.conf。

4. 使用 Web 或应用服务器提供的工具重新启动网关。

Linux: 安装或升级后设置 XMPP/HTTP 网关日志文件的位置

在 Linux 中，安装和配置 XMPP/HTTP 网关后，您需要修改 httpbind_log4j.conf 中 XMPP/HTTP 网关默认日志文件的位置。

1. 打开 httpbind_log4j.conf 文件。

   此文件的存储位置是您在 httpbind.conf 文件中指定作为 httpbind.log4j.config 参数的值。默认情况下，文件存储于默认 Instant Messaging 实例的以下目录中：

   im-cfg-base/httpbind_log4j.conf

2. 将 log4.appender.appender_ID.file 参数的值设为日志文件的存储位置。

更改 XMPP/HTTP 网关日志文件的位置

开始之前

确保您熟悉如 Apache Logging Services 网站中所述的 log4j 语法和一般的实现方法。

1. 打开 httpbind_log4j.conf。

   此文件的存储位置是您在 httpbind.conf 文件中指定作为 httpbind.log4j.config 参数的值。默认情况下，文件存储于默认 Instant Messaging 实例的以下目录中：

   im-cfg-base/httpbind_log4j.conf

2. 将 log4j.appender.appender-ID 参数的值设为您想要存储日志文件的位置。

3. 保存并关闭 httpbind_log4j.conf。

4. 重新启动 Web 容器。

使用 XMPP/HTTP 网关的非默认日志文件位置

如果您选择使用非默认的日志文件位置，则您需要修改 httpbind_log4j.conf 中 XMPP/HTTP 网关默认日志文件的位置。

1. 打开 httpbind_log4j.conf 文件。

   此文件的存储位置是您在 httpbind.conf 文件中指定作为 httpbind.log4j.config 参数的值。默认情况下，文件存储于默认 Instant Messaging 实例的以下目录中：

   im-cfg-base/httpbind_log4j.conf

2. 将 log4.appender.appender_ID.file 参数的值设为日志文件的存储位置。

设置 XMPP/HTTP 网关日志记录级别

开始之前

确保您熟悉如 Apache Logging Services 网站中所述的 log4j 语法和一般的实现。

1. 打开 httpbind_log4j.conf。

   此文件的存储位置是您在 httpbind.conf 文件中指定作为 httpbind.log4j.config 参数的值。默认情况下，文件存储于默认 Instant Messaging 实例的以下目录中：

   im-cfg-base/httpbind_log4j.conf

2. 将 log4j.logger.gateway 参数设为所需的日志记录级别。

   例如：

   log4j.logger.gateway=ERROR

   有关您可以使用的有效日志记录级别列表，参见表 13–1。

XMPP/HTTP 网关 log4j 日志配置文件语法

有关 log4j 语法和一般实现的详细信息，参见Apache Logging Services 网站。网关日志配置文件语法如下。

log4j.logger.gateway=logging-level, Appender-ID
# DEFAULT TO RollingFileAppender
log4j.appender.Appender-ID=org.apache.log4j.RollingFileAppender
log4j.appender.Appender-ID.file=log-dir/httpbind.log
log4j.appender.Appender-ID.append=true|false
log4j.appender.Appender-ID.maxBackupIndex=7
log4j.appender.Appender-ID.maxFileSize=max-log-file-size
log4j.appender.Appender-ID.layout=org.apache.log4j.PatternLayout
log4j.appender.Appender-ID.layout.ConversionPattern=log-entry-syntax

示例 10–1 XMPP/HTTP 网关日志配置文件 (httpbind_log4j.conf)

log4j.logger.gateway=ERROR, A1
# DEFAULT TO RollingFileAppender
log4j.appender.A1=org.apache.log4j.RollingFileAppender
# log4j.appender.A1.file=$(logdir)/gateway.log
log4j.appender.A1.file=/tmp/gatewaylog
log4j.appender.A1.append=true
log4j.appender.A1.maxBackupIndex=7
log4j.appender.A1.maxFileSize=5mb
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=[%d{DATE}] %-5p %c [%t] %m%n