第 10 章 使用 Instant Messaging XMPP/HTTP 閘道

XMPP/HTTP 閘道讓 Instant Messaging 能夠存取非 XMPP 式的用戶端，如 HTML 式用戶端，以及防火牆背後的用戶端 (允許 HTTP 通訊，但不允許 XMPP 通訊)。閘道會代表 HTTP 用戶端來代理到 XMPP 伺服器的 Instant Messaging 通訊。

XMPP/HTTP 閘道是由 Instant Messenger 資源檔案部署為 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 檔案語法、檔案位置和此檔案中配置參數的說明，請參閱附錄 Bhttpbind.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 檔案語法、檔案位置和此檔案中配置參數的說明，請參閱附錄 Bhttpbind.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