第 2 部分 管理作業

• 第 3 章, 啟動代理程式和用戶端

• 第 4 章, 配置代理程式

• 第 5 章, 管理代理程式

• 第 6 章, 管理實體目標

• 第 7 章, 管理安全性

• 第 8 章, 管理受管理物件

• 第 9 章, 使用代理程式叢集

• 第 10 章, 監視代理程式

• 第 11 章, 分析與調校訊息服務

• 第 12 章, 排解疑難問題

第 3 章 啟動代理程式和用戶端

安裝 Sun Java System^TM Message Queue^TM 並執行一些基本準備步驟後，就可以開始啟動代理程式和用戶端。代理程式的配置由一組配置檔案所管理，可由傳送給代理程式公用程式 (imqbrokerd) 的指令行選項加以置換；如需更多資訊，請參閱第 4 章, 配置代理程式。

本章包含下列各節：

• 準備系統資源

• 啟動代理程式

• 移除代理程式

• 啟動用戶端

準備系統資源

啟動代理程式之前，必須預先執行兩個系統層級的作業：同步化系統時鐘，以及 (在 Solaris 或 Linux 平台上) 設定檔案描述元限制。以下各節將描述這些作業。

同步化系統時鐘

啟動任何代理程式或用戶端之前，必須先將會與 Message Queue 系統互動的所有主機的時鐘同步化。如果您使用訊息過期設定 (即訊息有效存在的時間)，則此項同步化尤為重要。不同步的時鐘時間標記，可能會讓訊息無法按預期那樣過期或無法傳送訊息。同步化對代理程式叢集也十分重要。

您應該將系統配置為執行時間同步化協定，例如簡易網路時間協定 (SNTP)。Solaris 和 Linux 的 xntpd 常駐程式和 Windows 的 W32Time 服務通常可支援時間同步化功能。(如需配置此服務的詳細資訊，請參閱作業系統的文件。)代理程式執行後，請避免將系統時鐘往回設定。

設定檔案描述元限制

在 Solaris 和 Linux 平台上，執行用戶端或代理程式所在的 Shell，會對程序可以使用的檔案描述元數目指定軟式限制。在 Message Queue 中，用戶端建立的每個連線或代理程式接受的每個連線，均使用這些檔案描述元的其中一項。每個擁有永久性訊息的實體目標皆使用一個檔案描述元。

因此，檔案描述元限制會限制代理程式或用戶端可擁有的連線數目。依預設，Solaris 上的最大連線數目為 256，而 Linux 上為 1024。(實際上，因為會持續使用檔案描述元，所以連線限制會低於上述數目。)如果需要超過此限制的連線數目，您必須在執行用戶端或代理程式的每個 Shell 中，提高檔案描述元限制。如需如何執行此作業的資訊，請參閱 ulimit 線上手冊。

啟動代理程式

您可以使用 Message Queue 指令行公用程式或 Windows [開始] 功能表，以互動方式啟動代理程式，或是安排在系統啟動時自動啟動代理程式。以下各節描述如何：

以互動方式啟動代理程式

您可以使用代理程式公用程式 (imqbrokerd)，從指令行以互動方式啟動代理程式。(也可以從 Windows 的 [開始] 功能表，啟動代理程式。)您無法使用管理主控台 (imqadmin) 或指令公用程式 (imqcmd) 來啟動代理程式，因為必須先執行代理程式，才能使用這些工具。

在 Solaris 和 Linux 平台上，代理程式實例一律必須由最初啟動該實例的同一位使用者啟動。每個代理程式實例都有自己的配置特性和檔案式訊息存放區。初次啟動代理程式實例時，Message Queue 會使用該使用者的檔案建立模式遮罩 (umask)，設定包含該代理程式實例配置資訊和永久性資料之目錄的權限。

代理程式實例的預設名稱是 imqbroker。您只要使用下列指令，即可從指令行以該名稱和預設配置來啟動代理程式

imqbrokerd

該指令會在本地機器上使用預設連接埠 7676 上的連接埠對映器，啟動代理程式實例 imqbroker (請參閱連接埠對映器)。

若要指定非預設的實例名稱，請在 imqbrokerd 指令上使用 -name 選項。下列指令啟動的代理程式實例名稱是 myBroker：

imqbrokerd -name myBroker

您也可以在 imqbrokerd 指令行上使用其他選項來控制代理程式作業的各種狀況。下列範例使用 -tty 選項，向指令視窗傳送錯誤和警告 (標準輸出)：

imqbrokerd -name myBroker -tty

您也可以在指令行上使用 -D 選項來置換代理程式實例配置檔案 (config.properties) 中指定的特性值。此範例設定 imq.jms.max_threads 特性，將 jms 連線服務可用的最大執行緒數目提高到 2000：

imqbrokerd -name myBroker -Dimq.jms.max_threads=2000

如需 imqbrokerd 指令的語法、子指令和選項的詳細資訊，請參閱代理程式公用程式。如需這項資訊的快速摘要，請輸入下列指令：

imqbrokerd -help

如果您有 Sun Java System Message Queue Platform Edition 授權，則可以使用 imqbrokerd 指令的 -license 選項以啟動 Enterprise Edition 試用授權，試用 Enterprise Edition 功能 90 天。請指定授權名稱 try：

imqbrokerd -license try

每次啟動代理程式時，都必須使用此選項，否則代理程式會預設為標準 Platform Edition 授權。

自動啟動代理程式

除了從指令行明確啟動代理程式之外，您也可以設定在系統啟動時自動啟動代理程式。執行此作業的方式，會因執行代理程式的平台 (Solaris、Linux 或 Windows) 而有所不同。

在 Solaris 和 Linux 上自動啟動

在 Solaris 和 Linux 系統上安裝 Message Queue 時，可啟用自動啟動作業的程序檔位於 /etc/rc* 樹狀目錄中。若要使用這些程序檔，您必須編輯配置檔案/etc/imq/imqbrokerd.conf (Solaris) 或 /etc/opt/sun/mq/imqbrokerd.conf (Linux)，如下所示：

• 若要在系統啟動時自動啟動代理程式，請將 AUTOSTART 特性設定為 YES。

• 若要在異常結束後自動重新啟動代理程式，請將 RESTART 特性設定為 YES。

• 若要設定代理程式的啟動指令行引數，請指定一個或多個 ARGS 特性值。

在 Windows 上自動啟動

若要在 Windows 系統啟動時自動啟動代理程式，您必須將代理程式定義為 Windows 服務。然後就會在系統啟動時啟動代理程式，並且在背景中執行到系統關機為止。因此，除非您要啟動其他實例，否則不必使用 imqbrokerd 指令啟動代理程式。

一個系統只能有一個代理程式當成 Windows 服務來執行。[工作管理員] 會將這類代理程式當作兩個可執行的程序列出：

• 原生 Windows 服務包裝程式 imqbrokersvc.exe

• 執行代理程式的 Java 執行階段

在 Windows 系統上安裝 Message Queue 時，您可以將代理程式安裝為服務。安裝後，您可以使用服務管理員公用程式 (imqsvcadmin) 執行下列作業：

• 將代理程式新增為 Windows 服務

• 決定代理程式服務的啟動選項

• 移除當成 Windows 服務執行的代理程式

若要將啟動選項傳送給代理程式，可在 imqsvcadmin 指令中使用 -args 引數。它的作用等同於啟動代理程式中描述的 imqbrokerd 指令之 -D 選項。使用指令公用程式 (imqcmd) 以控制代理程式照常運作。

如需 imqsvcadmin 指令的語法、子指令和選項的完整資訊，請參閱服務管理員公用程式。

重新配置代理程式服務

如要重新配置安裝為 Windows 服務的代理程式，程序如下：

重新配置當成 Windows 服務執行的代理程式

1. 停止服務。

   1. 從 Windows [開始] 功能表的 [設定] 子功能表中，選擇 [控制台]。

   2. 開啟 [系統管理工具] 控制台。

   3. 選擇 [服務] 圖示以執行服務工具，然後從 [檔案] 功能表或快顯式環境功能表選擇 [開啟]，或是直接連按兩下該圖示。

   4. 在 [服務 (本機)] 下方，選擇 [Message Queue Broker] 服務，然後從 [執行] 功能表中選擇 [內容]。

      或者，您可以在 [訊息佇列代理程式] 上按一下滑鼠右鍵，然後從快顯功能表中選擇 [內容]，或直接連按兩下 [訊息佇列代理程式]。不論何種方式，都會出現 [訊息佇列代理程式特性] 對話方塊。

   5. 在 [內容] 對話方塊中的 [一般] 標籤下方，按一下 [停止] 即可停止代理程式服務。

2. 移除服務。

   在指令行上輸入指令

   imqsvcadmin remove

3. 重新安裝服務，使用 -args 選項指定不同的代理程式啟動選項，或使用 -vmargs 選項指定不同的 Java 版本引數。

   例如，若要將服務的主機名稱與連接埠號變更為 broker1 與 7878，可以使用以下指令

   imqsvcadmin install -args "-name broker1 -port 7878"

使用替代 Java 執行階段

您可以使用 imqsvcadmin 指令的 -javahome 或 -jrehome 選項，指定替代 Java 執行階段的位置。(您也可以在服務的 [內容] 對話方塊視窗中，從 [一般] 標籤下方的 [啟動參數] 欄位，指定這些選項。)

[啟動參數] 欄位會將反斜線字元 (\) 視為退出字元，因此當您以反斜線作為路徑區隔字元時，必須輸入兩次：例如：

-javahome c:\\j2sdk1.4.0

顯示代理程式服務啟動選項

若要決定代理程式服務的啟動選項，請在 imqsvcadmin 指令中使用 query 選項，如範例 3–1 所示。

範例 3–1 顯示代理程式服務啟動選項

imqsvcadmin query

Service Message Queue Broker is installed.
Display Name: Message Queue Broker
Start Type: Automatic
Binary location: C:\\Sun\\MessageQueue\\bin\\imqbrokersvc.exe
JavaHome: c:\\j2sdk1.4.0
Broker Args: -name broker1 -port 7878

服務啟動問題疑難排解

如果在啟動當成 Windows 服務的代理程式時出現錯誤，可以檢視記錄的錯誤事件：

查閱記錄的服務錯誤事件

1. 開啟 Windows [系統管理工具] 控制台。

2. 啟動 [事件檢視器] 工具。

3. 選擇 [應用程式事件記錄檔]。

4. 從 [執行] 功能表選擇 [重新整理]，以顯示任何錯誤事件。

移除代理程式

移除代理程式的程序會因平台不同而異，將會在以下各節說明。

移除 Solaris 或 Linux 上的代理程式

若要移除 Solaris 或 Linux 平台上的代理程式實例，請在 imqbrokerd 指令中使用 -remove 選項。指令格式如下：

imqbrokerd [options…] -remove instance

例如，如果代理程式的名稱是 myBroker，則指令如下：

imqbrokerd -name myBroker -remove instance

此指令可刪除所指定代理程式的整個實例目錄。

如果代理程式設定為在系統啟動時自動啟動，請編輯配置檔案 /etc/imq/imqbrokerd.conf (Solaris) 或 /etc/opt/sun/mq/imqbrokerd.conf (Linux)，將 AUTOSTART 特性設定為 NO。

如需 imqbrokerd 指令的語法、子指令和選項的詳細資訊，請參閱代理程式公用程式。如需這項資訊的快速摘要，請輸入下列指令：

移除 Windows 上的代理程式服務

若要移除當成 Windows 服務執行的代理程式，請使用以下指令

imqcmd shutdown bkr

若要關閉代理程式，請在後面加上

imqsvcadmin remove

以移除服務。

您也可以透過 [系統管理工具] 控制台，使用 Windows [服務] 工具，以停止和移除代理程式服務。

請在移除代理程式服務之後，重新啟動您的電腦。

啟動用戶端

啟動用戶端應用程式之前，您必須先向應用程式開發者取得系統的設定資訊。如果您啟動 Java 用戶端應用程式，就必須正確設定 CLASSPATH 變數，並且確定已安裝正確的 .jar 檔案。「Message Queue Developer's Guide for Java Clients」中包含設定系統的一般步驟資訊，但是您的開發者可能會提供額外的資訊。

啟動 Java 用戶端應用程式時，請使用下列的指令行格式：

java clientAppName

若要啟動 C 用戶端應用程式，請使用應用程式開發者提供的格式。

應用程式的文件應會提供與應用程式設定的屬性值相關的資訊；您可能要從指令行置換部分屬性值。您也可能要為任何使用 Java Naming and Directory Interface (JNDI) 查找功能尋找連線工廠的 Java 用戶端，在指令行中指定屬性。如果查找功能傳回的連線工廠比應用程式還舊，表示連線工廠不支援較新的屬性。在這種情況下，Message Queue 會將這些屬性設為預設值；必要時，您可以使用指令行置換這些預設值。

若要從指令行指定 Java 應用程式的屬性值，請使用以下語法：

java [[-Dattribute=value]
…] clientAppName

如第 16 章, 受管理物件屬性參照所述，attribute 的值必須是連線工廠受管理物件屬性。如果該值中含有空格，請將指令行的 attribute= value 部分括在引號內。

以下範例會啟動名稱為 MyMQClient 的用戶端應用程式，利用連接埠 7677 連線至主機 OtherHost 上的代理程式：

java -DimqAddressList=mq://OtherHost:7677/jms MyMQClient

指令行中指定的主機名稱與連接埠，會置換應用程式本身的任何設定。

有時您無法使用指令行來指定屬性值。管理員可以將受管理物件設為只能讀取，或應用程式開發者能以程式碼讓用戶端應用程式執行此作業。若要瞭解啟動用戶端程式的最佳方法，最好與應用程式開發者溝通交流。

第 4 章 配置代理程式

代理程式的配置由一組配置檔案和在啟動時傳給 imqbrokerd 指令的選項所管理。本章說明可用的配置特性，以及如何使用它們來配置代理程式。

本章包含下列各節：

• 代理程式服務

• 設定代理程式特性

• 配置永久性資料存放區

如需代理程式配置特性的完整參考資訊，請參閱第 14 章, 代理程式特性參照。

代理程式服務

視服務或服務影響所及的代理程式元件之不同，代理程式配置特性可分為數個種類：

• 連線服務：管理代理程式與其用戶端之間的實體連線，用來傳輸內送和外寄訊息。

• 路由服務：路由和傳送 JMS 有效負載訊息，並控制由訊息服務所使用的訊息，以支援透過可靠的方式進行傳送。

• 永久性服務：管理資料寫入永久性存放區，以及從永久性存放區擷取資料。

• 安全性服務：對連線到代理程式的使用者進行認證，並授權使用者執行動作。

• 監視服務：產生有關代理程式效能的度量與診斷資訊。

以下各節描述每項服務，以及針對特殊需求用以自訂服務的特性。

連線服務

訊息代理程式提供各種連線服務，以使用多種傳輸協定來支援應用程式與管理用戶端。與連線服務相關的代理程式配置特性，列於連線特性中。

表 4–1 顯示可用的連線服務，依據兩種特徵區分：

• 服務類型會指定此服務是提供 JMS 訊息傳送 (NORMAL)，或是提供 Message Queue^TM 管理服務 ( ADMIN)。

• 協定類型可指定基本的傳輸協定。

透過設定代理程式的 imq.service.activelist 特性，即可將代理程式配置為執行任一或所有這些連線服務。此特性的值是一組會在代理程式啟動時啟動的連線服務清單；若未明確指定此特性，將依預設啟動 jms 與 admin 服務。

每個連線服務也支援特定的認證與授權功能；如需更多資訊，請參閱安全性服務。

連接埠對映器

每種連線服務都是透過特定連接埠提供，此時需指定主機名稱 (或 IP 位址) 和連接埠號。您可以明確指定服務的靜態連接埠號，或由代理程式的連接埠對映器動態指定。連接埠對映器本身常駐於代理程式的主連接埠上，即通常位於標準連接埠號 7676 。(若有必要，您可以使用代理程式配置特性 imq.portmapper.port，以其他連接埠號來置換此值。)依預設，每個連線服務皆會在啟動時對連接埠對映器進行自我註冊。當用戶端建立與代理程式的連線時，Message Queue 用戶端執行階段會先連絡連接埠對映器，以請求連接埠號供需要的連線服務使用。

此外，您也可以使用 imq.serviceName.protocolType. port 配置特性置換連接埠對映器，並明確指定連線服務的靜態連接埠號 (其中 serviceName 與 protocolType 表示特定的連線服務，如表 4–1 所示)。(只有 jms、ssljms、admin 與 ssladmin 連線服務能夠以這種方式進行配置；httpjms 與 httpsjms 服務使用不同的配置特性，如附錄 CHTTP/HTTPS 支援 所述)。但是，靜態連接埠通常僅在特殊情況下使用，例如透過防火牆連線 (請參閱透過防火牆連線)，一般不建議使用。

在具有兩部或更多主機的環境下 (例如在電腦上安裝了多張網路卡時)，您可以使用代理程式特性來指定連線服務所要連結的主機。imq.hostname 特性可為所有連線服務指定單一的預設主機；而此預設值可在必要時，由下列特性所置換：imq.serviceName. protocolType.hostname (針對 jms、ssljms、admin 或 ssladmin 服務) 或 imq.portmapper.hostname (針對連接埠對映器本身)。

同時收到多個連接埠對映器請求時，這些請求會儲存在作業系統積存區中等候執行動作。imq.portmapper.backlog 特性會針對這些位於積存區中的請求，指定數量上限。超過此上限時，就會拒絕其他請求，直到積存區量降低為止。

執行緒池管理

每個連線服務均為多重執行緒，支援多重連線。代理程式會針對每個服務，在個別的執行緒池中維護這些連線所需的執行緒。在連線需要執行緒時，這些執行緒就會新增到執行緒池中，供支援該連線的服務使用。

您選擇的執行緒模型會指定執行緒是專屬於單一連線，還是由多個連線共用：

• 在專屬模型中，代理程式的每個連線均需要兩個執行緒：一個用於內送訊息，另一個用於外寄訊息。這會限制可支援的連線數量，但可確保較高的效能。

• 在共用模型中，連線在傳送或接收訊息時會由共用執行緒進行處理。此模型中的各個連線不需要專屬執行緒，因此能夠提高可用連線的數量，但會降低效能，因為必須使用較多資源來管理執行緒。

代理程式的 imq.serviceName. threadpool_model 特性，可指定已知連線服務應使用這兩種模型中的哪一種。此特性會採用下列兩個字串值之一： dedicated 或 shared。若未明確設定特性，則會依預設採用 dedicated。

您也可以設定代理程式特性 imq.serviceName. min_threads 與 imq.serviceName. max_threads，來指定服務執行緒池的最小與最大執行緒數。當可用的執行緒超過此最小臨界值時，Message Queue 將會在執行緒成為閒置狀態時關閉這些執行緒，直到再次達到最小值為止，以節省記憶體資源。在負載量較大的情況下，執行緒的數目會增加，直至達到執行緒池的最大數目為止；此時會拒絕新的連線，直至有執行緒變為可用為止。

共用執行緒模型會使用分散執行緒，將執行緒指定給使用中的連線。代理程式特性 imq.shared.connectionMonitor_limit 可指定由單一分散執行緒監視的最大連線數。此特性的值越小，執行緒指定給連線的速度就越快。imq.ping.interval 特性會指定一個以秒為單位的時間間隔，讓代理程式依此間隔定期測試 (「ping」) 連線，以驗證該連線是否仍在使用中，如此就可以預先偵測到連線失敗，避免所嘗試執行的訊息傳輸失敗。

路由服務

用戶端連線至代理程式後，即可路由訊息及傳送訊息。在此階段中，代理程式必須建立及管理不同類型的實體目標，以確保訊息能順利傳送並有效利用資源。您可以使用路由特性所述的代理程式配置特性，以根據應用程式需要的方式管理這些工作。

代理程式的效能和穩定性取決於記憶體之類的可用系統資源，以及利用這類資源的效率如何。您可以設定配置特性，以防止代理程式被大量內送訊息佔用，或防止記憶體不足。這些特性可在三個不同的層級上起作用，以確保訊息服務在資源不足的情況下仍可運作：

• 整個系統的訊息限制完全適用於系統上所有的實體目標。其中包括代理程式保留訊息的數量上限 (imq.system.max_count)，以及此類訊息所佔用的位元組總數上限 (imq.system.max_size)。若達到其中一項限制，代理程式就會拒絕任何新的訊息，直到擱置的訊息低於該限制為止。此外對個別訊息的容量上限 (imq.message.max_size) 與收回過期訊息的時間間隔 (imq.message.expiration.interval) 方面，也有相關的限制。

• 個別目標限制會控制傳送到特定實體目標的訊息流量。控制這些限制的配置特性在第 15 章, 實體目標特性參照中有所說明。這些限制包括：目標所能保留的訊息數量與容量、所能建立的訊息產生器與用戶的數量，以及可納入相同批次傳送到目標的訊息數量等等。

  目標可配置為透過下列方式回應記憶體限制：減緩訊息產生者傳送訊息的速度、拒絕新的內送訊息，或丟棄最舊或優先權最低的現有訊息。以這種方式從目標中刪除的訊息，可選擇移至停用的訊息佇列中，而不是直接捨棄；代理程式特性 imq.destination.DMQ.truncateBody 可控制是整個訊息內文還是只有標頭與特性資料儲存在停用的訊息佇列中。

  為了在開發及測試應用程式時方便作業，您可以配置訊息代理程式，使其在訊息產生器或用戶嘗試存取不存在的目標時，自動建立新的實體目標。表 14–3 中所摘要的代理程式特性與剛剛說明的特性相同，但適用於自動建立的目標，而非管理員所建立的目標。

• 系統記憶體臨界值定義了記憶體用量的層級，代理程式會依據這些層級採取越來越嚴格的動作，以便防止記憶體超載。 這類的用量定義共有四種：

  • 綠色：有大量記憶體可用。

  • 黃色：代理程式記憶體開始減少。

  • 橙色：代理程式記憶體不足。

  • 紅色：代理程式無記憶體可用。

    用以定義這些層級的記憶體用量百分比，分別由代理程式特性 imq.green.threshold、 imq.yellow.threshold、 imq.orange.threshold 與 imq.red.threshold 所指定，預設值為綠色 0%、 黃色 80%、橙色 90%、紅色 98%。

    記憶體用量到達下一層級時，代理程式即會按階段做出回應，首先將訊息由使用中記憶體移出至永久性存放區，然後減少產生器產生的非永久性訊息，直到最後停止訊息傳入代理程式中。(上述兩種方法皆會降低代理程式效能。)若要減少產生的訊息，必須將每個批次作業大小限制為 imq.resourceState .count 特性所指定的訊息數，其中 resourceState 分別為green、yellow、orange 或 red。

這些系統記憶體臨界值被觸發時，表示整個系統與目標的訊息限制可能設定得太高。由於記憶體臨界值不一定總能及時偵測到可能的記憶體超載，因此您不應根據它們來控制記憶體用量，而應重新配置整個系統與目標限制，使記憶體資源最佳化。

永久性服務

如果要在代理程式故障時回復，則此代理程式需要重新建立其訊息傳送作業的狀態。為執行此作業，代理程式必須將狀態資訊儲存到永久性資料存放區。重新啟動代理程式時，它會使用儲存的資料來重新建立目標和長期訂閱、回復永久性訊息、回復開啟的作業事件，並為未傳送的訊息重新建立路由表。然後，它可以重新繼續訊息傳送。

Message Queue 支援檔案式與 JDBC 型永久性模組 (請參閱圖 4–1)。檔案式永久性會使用個別的檔案來儲存永久性資料；而 JDBC 型永久性則使用 Java 資料庫連結 (JDBC™) 介面，將代理程式連線至與 JDBC 相容的資料存放區。檔案式永久性通常快於 JDBC 型永久性；但是某些使用者偏好 JDBC 相容存放區所提供的備援和管理控制功能。代理程式配置特性 imq.persist.store (請參閱表 14–4) 可指定使用哪一種形式的永久性。

圖 4–1 永久性資料存放區

檔案式永久性

依預設，Message Queue 會使用檔案式永久性資料存放區，其中的個別檔案會儲存如訊息、目標、長期訂閱與作業事件等永久性資料。與檔案式永久性相關的代理程式配置特性，會在檔案式永久性中列出。

檔案式存放區位於以資料存放區所屬之代理程式實例的名稱 (instanceName) 作為辨識依據的目錄中：

…/instances/instanceName
/fs350/

(請參閱附錄 AMessage Queue^TM 資料的特定平台位置，以瞭解 instances 目錄的所在位置。)代理程式上的每個目標，都會將其保留訊息的子目錄傳送到該目標上。

由於永久性資料存放區可能包含機密或專有訊息，因此您應保護 …/instances/ instanceName/fs350/ 目錄的安全性，以防止未經授權的存取；請參閱保護永久性資料。

除了訊息以外的所有永久性資料，都儲存於個別的檔案中：其中一個檔案用於儲存目標、一個檔案用於儲存長期訂閱，一個檔案用於儲存作業事件狀態資訊。大部分訊息會儲存在由變數型記錄組成的單一檔案中。您可以壓縮此檔案，以便減少新增或移除訊息時的分段程序 (請參閱壓縮實體目標)。此外，超過特定臨界值大小的訊息會儲存於自身的個別檔案中，而非儲存於變數型記錄檔案。您可以使用代理程式特性 imq.persist.file.message.max_record_size 配置此臨界值大小。

代理程式會為這些個別訊息檔案維護一個檔案池：檔案不再使用時，不會被直接刪除，而會傳回其目標目錄中容納閒置檔案的檔案池中，以供日後其他訊息重複使用。代理程式特性 imq.persist.file.destination.message.filepool.limit 可指定池中的最大檔案數。當目標中的個別訊息檔案數超過此限制時，若檔案已不需使用，就會直接被刪除，而不會傳回池中。

將檔案傳回檔案池時，代理程式可直接將檔案標記為可供重複使用，而不需刪除其先前的內容，這樣做可節省時間，但會耗用儲存空間。您可以使用 imq.persist.file.message.filepool.cleanratio 代理程式特性，指定每個目標的檔案池中有多少百分比的檔案應保持為「清除」(空白) 狀態，而非直接標記為可供重複使用的狀態。此值設得越高，檔案池所需的空間就越少，但在檔案傳回池後，則需要較多的系統資源來清除檔案的內容。若代理程式的 imq.persist.file.message.cleanup 特性為 true，則池中所有的檔案就會在代理程式關閉時被清空，而成為清除狀態；如此將可節省儲存空間，但會減緩關閉程序的速度。

作業系統將資料寫入永久性存放區時，可選擇應以同步還是「延遲」(非同步) 的方式寫入資料。在系統當機的情況下，若代理程式認為資料已寫入永久性存放區，但事實上並非如此時，延遲儲存就可能導致資料遺失。為確保完全的可靠性 (必須犧牲效能)，您可以將代理程式特性 imq.persist.file.sync.enabled 設為 true，使所有資料皆以同步方式寫入。如此一來，當系統從當機狀態回復時將必定會有可用的資料，讓代理程式能可靠地重新繼續執行作業。但請注意，雖然資料並未遺失，但叢集內的任何其他代理程式無法使用這些資料，因為叢集代理程式此時並未共用資料。

JDBC 型永久性

您也可以不使用檔案式永久性，而設置代理程式存取任何可透過 JDBC 相容驅動程式存取的資料存放區。其中包含設定適當的 JDBC 相關代理程式配置特性，以及使用資料庫管理者公用程式 (imqdbmgr)，建立具有適當模式的資料庫。如需詳細資訊，請參閱配置 JDBC 型存放區。

配置代理程式使用 JDBC 資料庫的特性，列於JDBC 型永久性中。您可以透過以下方式指定這些特性：使用每個代理程式實例的實例配置檔 (config.properties)，或者使用代理程式公用程式 (imqbrokerd) 或資料庫管理者公用程式 (imqdbmgr) 的 -D 指令行選項。

imq.persist.jdbc.driver 特性可提供在連線資料庫時要使用的 JDBC 驅動程式之 Java 類別名稱。另外還有特性可指定連線至現有資料庫 (imq.persist.jdbc.opendburl)、建立新資料庫 (imq.persist.jdbc.createdburl) 以及關閉資料庫連線 (imq.persist.jdbc.closedburl) 時所需的 URL。

imq.persist.jdbc.user 與 imq.persist.jdbc.password 特性可提供存取資料庫所需的使用者名稱與密碼；imq.persist.jdbc.needpassword 是指定是否需要密碼的布林值旗標。基於安全理由，密碼僅能在透過 -passfile 指令行選項所指定的密碼檔案中指定；若未指定此密碼檔案，imqbrokerd 與 imqdbmgr 指令就會以互動方式提示使用者提供密碼。同樣地，使用者名稱也可以從指令行上透過 imqbrokerd 指令的 -dbuser 選項，或 imqdbmgr 的 -u 選項提供。

由多個代理程式實例共用的 JDBC 資料庫中，配置特性 imq.persist.jdbc.brokerid 可為每個實例指定唯一的實例識別碼，以附加到資料庫表格的名稱中。(由於內嵌式資料庫僅為一個代理程式實例儲存資料，因此通常不需要此屬性。)其餘與 JDBC 相關的配置特性，可用以自訂建立資料庫模式的 SQL 程式碼，每個資料庫表格各有一個適用的特性。例如，imq.persist.jdbc.table.IMQSV35 特性提供的 SQL 指令可用以建立版本表格；imq.persist.jdbc.table.IMQCCREC35 可用於建立配置變更記錄表格；imq.persist.jdbc.table.IMQDEST35 則用於建立目標表格... 等等。請參閱表 14–6 以取得完整清單。

由於資料庫系統所需的 SQL 語法有所不同，因此請務必查看資料庫供應商提供的文件，以瞭解詳細資訊。

安全性服務

Message Queue 可提供使用者存取控制 (認證與授權) 與加密所需的安全性服務：

• 認證可確保只有經過驗證的使用者才能與代理程式建立連線。

• 授權可指定哪些使用者或群組有存取資源及執行特定作業的權限。

• 加密可保護訊息，以防透過連線傳送時遭到篡改。

身為 Message Queue 管理員，您必須負責設定代理程式進行使用者認證及使用者授權作業時所需的資訊。與安全性服務相關的代理程式特性，列於安全性特性中。布林值特性 imq.accesscontrol.enabled 的角色為主開關，可控制是否要將存取控制套用於整個代理程式；若要進行細部控制，您可置換特定連線服務的此設定，只要設定 imq.serviceName .accesscontrol.enabled 特性即可，其中 serviceName 是連線服務的名稱，如表 4–1 所示：例如 imq.httpjms.accesscontrol.enabled。

圖 4–2 顯示代理程式提供認證與授權服務時所需的元件。這些服務取決於包含訊息傳送系統使用者相關資訊的使用者儲存庫：其名稱、密碼與群組成員身份。此外，若要為使用者或群組的特定作業授權，代理程式必須查詢存取控制特性檔案，因為此檔案指定了使用者或群組可執行的作業。您可以使用配置特性 imq.accesscontrol.file.filename 為整個代理程式指定單一存取控制特性檔案，也可以使用 imq.serviceName. accesscontrol.file.filename，為單一連線服務指定存取控制特性檔案。

圖 4–2 安全性支援

如圖 4–2 所示，您可以將使用者資料儲存在隨附於 Message Queue 服務的平面檔案使用者儲存庫中，也可以外掛至預先存在的簡易目錄存取協定 (LDAP) 儲存庫：

• 若您選擇平面檔案儲存庫，就必須使用 Message Queue 使用者管理員公用程式 (imqusermgr) 管理儲存庫。此為內建選項，使用非常方便。

• 如果要使用現有的 LDAP 伺服器，可以使用 LDAP 供應商提供的工具來寫入和管理此使用者儲存庫。此外，您必須在代理程式的實例配置檔案中設定特性，讓代理程式能查詢 LDAP 伺服器，以取得使用者和群組的相關資訊。

代理程式的 imq.authentication.basic.user_repository 特性可指定要使用的儲存庫類型。一般而言，如果延展性很重要，或者如果需要不同代理程式共用儲存庫 (例如在使用代理程式叢集的情況下)，則使用 LDAP 儲存庫是不錯的選擇。如需設置平面檔案或 LDAP 使用者儲存庫的更多資訊，請參閱使用者認證。

認證

請求連線至代理程式的用戶端必須提供使用者名稱與密碼，供代理程式將其與使用者儲存庫中儲存的資料進行比較。從用戶端傳輸到代理程式的密碼，會以 Base64 編碼 (適用於平面檔案儲存庫) 或訊息摘要 (MD5) 雜湊法 (適用於 LDAP 儲存庫) 進行編碼。選擇哪一種編碼方式，由代理程式的 imq.authentication.type 特性整體控制，或由特定連線服務的 imq.serviceName. authentication.type 控制。imq.authentication.client.response.timeout 特性會設定認證請求的逾時時間間隔。

如密碼檔案所述，您可以選擇將密碼存入密碼檔案中，而不需以互動方式提示您提供密碼。布林值代理程式特性 imq.passfile.enabled 可控制此選項。若此特性為 true，imq.passfile.dirpath 與 imq.passfile.name 特性就會提供密碼檔案的目錄路徑與檔案名稱。imq.imqcmd.password 特性 (可內嵌於密碼檔案中) 可指定管理使用者在使用指令公用程式 (imqcmd) 管理代理程式、連線服務、連線、實體目標、長期訂閱與作業事件所使用的認證密碼。

若您使用 LDAP 型使用者儲存庫，則能使用多種代理程式特性來配置 LDAP 查找的各種設定。LDAP 伺服器本身的位址 (主機名稱與連接埠號) 由 imq.user_repository.ldap.server 所指定。imq.user_repository.ldap.principal 特性會提供連結到 LDAP 儲存庫所需的辨別名稱，而 imq.user_repository.ldap.password 則會提供相關的密碼。其他特性會指定個別使用者與群組搜尋的目錄基底與選用 JNDI 篩選器，以及使用者和群組名稱的提供者專用屬性識別碼等等；請參閱安全性特性以瞭解詳細資訊。

授權

經過認證後，使用者即有權執行各項 Message Queue 的相關活動。身為 Message Queue 管理員，您可以定義使用者群組，並指定其個別的使用者成員身份。預設的存取控制特性檔案僅明確參考一個群組 admin (請參閱群組)。此群組中的使用者具有 admin 連線服務的連線權限，此權限可讓使用者執行管理功能，如建立目標、監視及控制代理程式。依預設，您定義的任何其他群組中的使用者，均無法取得 admin 服務連線。

當使用者嘗試執行作業時，代理程式會檢查使用者名稱和群組成員身份 (從使用者儲存庫)，是否與為存取此作業所指定的那些名稱和成員身份 (在存取控制特性檔案中) 相符。存取控制特性檔案可指定以下作業的權限給使用者或群組：

• 連線至代理程式

• 存取目標：為任何給定目標或所有目標建立用戶、產生器或佇列瀏覽器

• 自動建立目標

加密

若要加密在用戶端與代理程式之間傳送的訊息，您需要使用基於安全通訊端層 (SSL) 標準的連線服務。透過在已啟用 SSL 的代理程式與用戶端之間建立加密的連線，SSL 可提供連線層級的安全性。

若要使用 SSL 型的 Message Queue 連線服務，您必須使用金鑰工具公用程式 (imqkeytool)，產生成對的私密金鑰/公開金鑰。此公用程式會將公開金鑰內嵌於自我簽署的憑證中，並放置在 Message Queue 金鑰庫中。金鑰庫本身受密碼保護；若要解除鎖定，您必須在啟動時提供由 imq.keystore.password 特性所指定的金鑰庫密碼。一旦金鑰庫解除鎖定，代理程式即可將憑證傳送至請求連線的任何用戶端。然後，用戶端即可使用此憑證設定與代理程式的加密連線。

imq.audit.enabled 代理程式特性可控制記錄到 Message Queue 代理程式記錄檔中的稽核記錄；如需更多資訊，請參閱稽核記錄。

監視服務

代理程式包含可監視和診斷應用程式和代理程式效能的元件。這些元件包括：

• 產生資料的元件，即度量產生器與記錄事件的代理程式程式碼

• 記錄程式元件，可將輸出資訊寫入到多個輸出通道

• 度量訊息產生者，可將包含度量資訊的 JMS 訊息傳送到主題目標，以供 JMS 監視用戶端使用

圖 4–3 說明一般方案。用以配置監視服務的代理程式特性，列於檢視特性中。

圖 4–3 監視支援

度量產生器

度量產生器可提供代理程式作業的相關資訊，例如傳入和傳出代理程式的訊息流量、代理程式記憶體中的訊息數量和使用的記憶體、開啟連線的數量，以及使用的執行緒數量。布林值代理程式特性 imq.metrics.enabled 可控制是否記錄此類資訊；imq.metrics.interval 則指定記錄的頻率。

記錄程式

記錄程式會擷取代理程式程式碼與度量產生器所產生的資訊，並將此資訊寫入標準輸出 (主控台)、記錄檔；若在 Solaris 平台上，在發生錯誤時則會寫入 syslog 常駐程式程序。 imq.log.file.dirpath 與 imq.log.file.filename 代理程式特性會指定要使用的記錄檔；imq.log.console.stream 會指定主控台輸出應導向 stdout 還是 stderr。

imq.log.level 特性可控制記錄程式所收集的度量資訊種類：ERROR、WARNING 或 INFO。每個層級都會包含更高的層級，因此，若您指定 WARNING 作為記錄層級，則也會記錄錯誤訊息。imq.log.console.output 與 imq.log.file.output 特性分別控制哪些指定的種類會寫入主控台與記錄檔。但在此情況下，種類不包含比自身更高的層級；例如，如果要將錯誤與警告寫入記錄檔，且將參考訊息寫入主控台時，必須明確將 imq.log.file.output 設為 ERROR|WARNING，將 imq.log.console.output 設為 INFO。在 Solaris 平台上有另一個特性 imq.log.syslog.output，可指定要寫入 syslog 常駐程式的度量資訊種類。另外還有 imq.destination.logDeadMsgs 特性，可指定在停用的訊息被捨棄或移至停用的訊息佇列時，是否要加以記錄。

對於記錄檔，您可以指定何時關閉該檔案並將輸出自動重建至新的記錄檔。一旦記錄檔達到指定的大小 (imq.log.file.rolloverbytes) 或存在時間 (imq.log.file.rolloversecs)，就會將其儲存並建立新的記錄檔。

請參閱檢視特性，以瞭解與記錄有關的其他代理程式特性，並參閱配置及使用代理程式記錄功能，以進一步瞭解如何配置記錄程式，以及如何利用記錄程式取得效能資訊。

度量訊息產生者 (企業版)

度量訊息產生者會在固定時間間隔接收度量產生器傳送的資訊，並將資訊寫入度量訊息，接著根據訊息中包含的度量資訊類型，將訊息傳送到其中一個度量主題目標 (請參閱表 4–2)。訂閱這些度量主題目標的 Message Queue 用戶端，可以使用這些訊息並處理訊息所包含的度量資料。這允許開發者建立自訂監視工具以支援訊息傳送應用程式。如需每個度量訊息類型中所報告之度量數目的詳細資訊，請參閱「Message Queue Developer's Guide for Java Clients」。

代理程式特性 imq.metrics.topic.enabled 與 imq.metrics.topic.interval，可分別控制訊息是否要傳送到度量主題目標及傳送的頻率。imq.metrics.topic.timetolive 與 imq.metrics.topic.persist 特性可指定此類訊息的使用期限及其是否具有永久性。

除了度量訊息內文包含的資訊外，每個訊息的標頭還包含提供下列額外資訊的特性：

• 訊息類型

• 傳送訊息之代理程式的位址 (主機名稱與連接埠號)

• 度量範例需要的時間

這些特性對處理不同類型或不同代理程式的度量訊息之用戶端應用程式十分有用。

設定代理程式特性

您可以使用下列兩種方法之一來指定代理程式的配置特性：

• 編輯代理程式的配置檔案

• 直接從指令行提供特性值

以下兩節將說明這兩種配置代理程式的方法。

配置檔案

代理程式配置檔案含有配置代理程式時所需的特性設定。這些設定會根據您所使用的作業系統平台存放在適當的目錄中；請參閱附錄 AMessage Queue^TM 資料的特定平台位置，以瞭解詳細資訊。此目錄儲存以下檔案：

• 預設配置檔案 default.properties，在啟動時載入。此檔案不可編輯，但您可以閱讀此檔案以確定預設值，並找到要變更之特性的確切名稱。

• 安裝配置檔案 install.properties，包含安裝 Message Queue 時指定的所有屬性。此檔案在安裝後無法編輯。

此外，各個代理程式實例也有其本身的實例配置檔案，如下所述。如果您連線叢集中的代理程式實例，可能還需要使用叢集配置檔案以指定叢集配置資訊；如需更多資訊，請參閱叢集配置特性。

啟動時，代理程式會合併不同配置檔案中的特性值。如圖 4–4 所示，這些檔案會形成一個階層，在此階層中，實例配置檔案的指定值會置換安裝配置檔案中的指定值，而安裝配置檔案中的指定值則會置換預設配置檔案中的指定值。在階層頂端，您可以手動置換任何在配置檔案中指定的特性值，只要使用 imqbrokerd 指令的指令行選項即可。

圖 4–4 代理程式配置檔案

編輯實例配置檔案

首次執行代理程式時，會為該代理程式實例建立一個包含配置特性的實例配置檔案。此實例配置檔案名為 config.properties，儲存在以其所屬之代理程式實例名稱所識別的目錄中：

…/instances/ instanceName/props/config.properties

(請參閱附錄 AMessage Queue^TM 資料的特定平台位置，以瞭解 instances 目錄的所在位置。)若該檔案不存在，您必須在啟動代理程式時使用 -name 選項 (請參閱代理程式公用程式)，指定可供 Message Queue 建立檔案的實例名稱。

instances/instanceName 目錄和實例配置檔案，歸其對應的代理程式實例的建立者所有。代理程式實例必須始終由同一個使用者重新啟動。

實例配置檔案由代理程式實例所維護，並會在您使用 Message Queue 管理公用程式變更配置時進行修改。您也可以手動編輯實例配置檔案，以自訂代理程式的運作方式與資源使用。若要執行此動作，您必須是 instances/ instanceName 目錄的擁有者，或以 root 的身份登入並變更目錄的存取權限。

代理程式只能在啟動時讀取其實例配置檔案。若要對代理程式的配置進行永久性的變更，必須先關閉代理程式並編輯檔案，然後再重新啟動代理程式。該檔案 (或任何配置檔案) 中的特性定義會使用下列語法：

propertyName=value [[,value1] …]

例如，以下項目指定代理程式會在記憶體和永久性存放區中最多保留 50,000 個訊息，之後則會拒絕其他訊息：

imq.system.max_count=50000

以下項目指定每天 (86,400 秒) 會建立一個新的記錄檔：

imq.log.file.rolloversecs=86400

請參閱代理程式服務與第 14 章, 代理程式特性參照，以瞭解可用代理程式配置特性及其預設值的相關資訊。

從指令行設定配置選項

您可以在啟動代理程式時或啟動之後，在指令行上輸入代理程式配置選項。

啟動時，可以使用代理程式公用程式 (imqbrokerd) 來啟動代理程式實例。使用指令的 -D 選項，可用以指定任何代理程式配置特性及其值；如需更多資訊，請參閱啟動代理程式與代理程式公用程式。如果您使用服務管理員公用程式 (imqsvcadmin) 將代理程式啟動為 Windows 服務，則 -args 選項可用來指定啟動配置特性；請參閱服務管理員公用程式。

執行代理程式實例時，您也可以變更某些代理程式特性。若要修改執行中代理程式的配置，可以使用指令公用程式的 imqcmd update bkr 指令；請參閱更新代理程式特性與代理程式管理。

配置永久性資料存放區

代理程式的永久性資料存放區中含有實體目標、長期訂閱、訊息、作業事件與確認等項目的相關資訊。Message Queue 代理程式的預設配置會使用檔案式永久性存放區，但您可以重新配置，以外掛可透過 JDBC 相容驅動程式加以存取的任何資料存放區。 代理程式配置特性 imq.persist.store (請參閱表 14–4) 可指定使用哪一種形式的永久性。

本節將說明如何設定代理程式使用永久性存放區。它包括以下主題：

• 配置檔案式存放區

• 配置 JDBC 型存放區

• 保護永久性資料

配置檔案式存放區

建立代理程式實例時，會自動建立檔案式資料存放區。此存放區位於代理程式的實例目錄中；請參閱附錄 AMessage Queue^TM 資料的特定平台位置，以瞭解確切位置。

依預設，Message Queue 會以非同步方式將作業寫入至磁碟。作業系統可以緩衝這些作業，以提供更好的效能。但是，如果寫入作業期間發生意外的系統失敗，則訊息可能會遺失。若要增強可靠性 (必須犧牲效能)，您可以設定代理程式特性 imq.persist.file.sync，改為以同步方式寫入資料。如需此特性的詳細討論，請參閱檔案式永久性與表 14–5。

啟動代理程式實例時，可以使用 imqbrokerd 指令的 -reset 選項來清除檔案系統存放區。如需此選項及其子選項的更多資訊，請參閱代理程式公用程式。

配置 JDBC 型存放區

若要配置讓代理程式使用 JDBC 型永久性，請在代理程式的實例配置檔案中設定與 JDBC 相關的特性，並且建立適當的資料庫模式。Message Queue 資料庫管理者公用程式 (imqdbmgr) 使用 JDBC 驅動程式和代理程式配置特性來建立及管理資料庫。也可以使用資料庫管理者從資料庫中刪除毀壞的表格，或使用其他資料庫作為資料存放區。如需更多資訊，請參閱資料庫管理者公用程式。

Oracle 和 PointBase 資料庫產品有範例配置可供使用。這些檔案的位置視平台而異，且已列在附錄 AMessage Queue^TM 資料的特定平台位置 相關表格的「範例應用程式與配置」中。此外，PointBase 內嵌式版本、PointBase 伺服器版本與 Oracle 的範例，會在實例配置檔案 config.properties 中以註釋值的形式提供。

配置 JDBC 型資料存放區

1. 在代理程式的配置檔案中設定與 JDBC 相關的特性。

   相關特性在JDBC 型永久性中討論並於表 14–6 中列出。特別是，您必須將代理程式 imq.persist.store 特性設為 jdbc (請參閱永久性特性)。

2. 將 JDBC 驅動程式 .jar 檔案的副本或符號連結放入下列位置：

   • 在 Solaris 上：

     /usr/share/lib/imq/ext/

   • 在 Linux 上：

     /opt/sun/mq/share/lib/

   • 在 Windows 上：

     IMQ_VARHOME\\lib\\ext

   例如，若您要在 Solaris 系統上使用 PointBase，下列指令就會將驅動程式的 .jar 檔案複製到適當的位置上：

   % cp j2eeSDKInstallDirectory/pointbase/lib/pointbase.jar /usr/share/lib/imq/ext

   下列指令則會建立符號連結：

   % ln -s j2eeSDKID/lib/pointbase/pointbase.jar /usr/share/lib/imq/ext

3. 建立 Message Queue 永久性所需的資料庫模式。

   使用 imqdbmgr create all 指令 (針對內嵌式資料庫) 或 imqdbmgr create tbl 指令 (針對外部資料庫)；請參閱資料庫管理者公用程式。

   1. 變更 imqdbmgr 所在的目錄：

      • 在 Solaris 上：

        cd /usr/bin

      • 在 Linux 上：

        cd /opt/sun/mq/bin

      • 在 Windows 上：

        cd IMQ_HOME\\bin

   2. 輸入 imqdbmgr 指令：

      imqdbmgr create all

      ---

      備註 –

      若使用內嵌式資料庫，最好在下列目錄中建立：

      … /instances/ instanceName/dbstore/ databaseName

      如果內嵌式資料庫沒有使用者名稱和密碼保護，則可能由檔案系統權限所保護。若要確保代理程式可讀取和寫入資料庫，則執行此代理程式的使用者應與使用 imqdbmgr 指令建立內嵌式資料庫的使用者相同。

      ---

保護永久性資料

永久性存放區可以包含暫時儲存的訊息檔案和其他資訊。由於這些訊息可能包含專用資訊，請務必保護資料存放區，以防止未經授權的存取。本節將說明如何確保檔案式或 JDBC 型資料存放區的資料安全。

保護檔案式存放區

使用檔案式永久性的代理程式，會將永久性資料寫入平面檔案資料存放區中，而此存放區的位置會隨平台而有所不同 (請參閱附錄 AMessage Queue^TM 資料的特定平台位置)：

…/instances/ instanceName/fs350/

其中，instanceName 是識別代理程式實例的名稱。

instanceName/fs350/ 目錄會在代理程式實例首次啟動時建立。保護此目錄的程序取決於執行代理程式所在的作業系統平台：

• 在 Solaris 與 Linux 上，目錄的權限取決於啟動代理程式實例之使用者的檔案模式建立遮罩 (umask)。因此，透過適當地設定遮罩，即可限制啟動代理程式實例和讀取其永久性檔案的權限。此外，管理員 (超級使用者) 可以透過將 instances 目錄的權限設定為 700，保護永久性資料。

• 在 Windows 上，目錄的權限可透過 Windows 作業系統所提供的機制來設定。這通常需要開啟目錄的 [內容] 對話方塊。

保護 JDBC 型存放區

使用 JDBC 型永久性的代理程式，會將永久性資料寫入與 JDBC 相容的資料庫中。對於由資料庫伺服器所管理的資料庫 (例如 Oracle)，建議您建立使用者名稱和密碼，以存取 Message Queue 資料庫表格 (表格名稱以 IMQ 開頭)。如果資料庫不允許保護個別表格，請建立僅由 Message Queue 代理程式使用的專用資料庫。請參閱資料庫供應商提供的文件，以取得如何建立使用者名稱及密碼存取的相關資訊。

代理程式開啟資料庫連線所需的使用者名稱和密碼，可透過代理程式配置特性來提供。但若在啟動代理程式時將其作為指令行選項提供，則有更高的安全性，方法是使用 imqbrokerd 指令的 -dbuser 與 -dbpassword 選項 (請參閱代理程式公用程式)。

對於代理程式透過資料庫的 JDBC 驅動程式直接存取的內嵌式資料庫，通常是透過設定檔案在儲存永久性資料的目錄上的權限來確保此資料庫的安全，保護檔案式存放區中會有詳細說明。但是為確保代理程式和資料庫管理者公用程式都能讀取和寫入該資料庫，兩者應該由同一位使用者執行。

第 5 章 管理代理程式

本章說明如何使用 imqcmd 公用程式以管理代理程式及其服務。本章包含下列各節：

• 必要條件必要條件

• 使用 imqcmd 公用程式使用 imqcmd 公用程式

• 顯示代理程式資訊

• 更新代理程式特性

• 暫停和重新繼續代理程式

• 關閉和重新啟動代理程式

• 顯示代理程式度量

• 管理連線服務

• 取得有關連線的資訊

• 管理長期訂閱

• 管理作業事件

本章未包含有關管理代理程式的所有相關主題。下列幾章包含其他主題：

• 在代理程式上管理實體目標。如需有關如何建立、顯示、更新和銷毀實體目標，以及如何使用停用的訊息佇列等主題的資訊，請參閱第 6 章, 管理實體目標。

• 設定代理程式的安全性。如需有關使用者認證、存取控制、加密、密碼檔案和稽核記錄等主題的資訊，請參閱第 7 章, 管理安全性。

必要條件

您可以使用 imqcmd 和 imqusermgr 指令行公用程式來管理代理程式。管理代理程式前，請先執行以下作業：

• 使用 imqbrokerd 公用程式指令啟動代理程式。代理程式執行後，才能使用其他指令行公用程式。

• 決定是要設定 Message Queue^TM 管理使用者，或是使用預設帳號。您必須指定使用者名稱和密碼，才能使用管理指令。

  當您安裝 Message Queue 時，同時也會安裝預設平面檔案使用者儲存庫。此儲存庫出廠時隨附兩個預設項目：admin 使用者和 guest 使用者。測試 Message Queue 時，您可以使用預設使用者名稱和密碼 (admin/ admin) 來執行 imqcmd 公用程式。

  設定生產系統時，必須設定認證及授權管理使用者。如需設定檔案式使用者儲存庫或配置使用 LDAP 目錄伺服器的詳細資訊，請參閱第 7 章, 管理安全性。在生產環境中使用非預設使用者名稱和密碼，較為安全。

• 如果您要與代理程式之間使用安全的連線，請在目標代理程式實例上設定並啟用 ssladmin 服務。如需更多資訊，請參閱訊息加密。

使用 imqcmd 公用程式

imqcmd 公用程式能讓您管理代理程式及其服務。

如需 imqcmd 指令的語法、子指令和選項等參考資訊，請參閱第 13 章, 指令行參照。管理實體目標的參考資訊另外位於第 15 章, 實體目標特性參照中。

顯示說明

若要顯示 imqcmd 公用程式的說明，請使用 -h 或 -H 選項，且不可使用子指令。您無法取得特定子指令的說明。

例如，下列指令顯示 imqcmd 的說明：

imqcmd -H

如果您輸入的指令行除了子指令或其他選項之外，另包含 -h 或 -H 選項，則 imqcmd 公用程式只會處理 -h 或 -H 選項。忽略指令行的所有其他項目。

顯示產品版本

若要顯示 Message Queue 產品版本，可以使用 -v 選項。例如：

imqcmd -v

如果您輸入的指令行除了子指令或其他選項之外，另包含 -v 選項，則 imqcmd 公用程式只會處理 -v 選項。忽略指令行的所有其他項目。

指定使用者名稱和密碼

每個 imqcmd 子指令都要經由使用者儲存庫進行認證，因此需要使用者名稱和密碼。只有使用 -h 或 -H 選項來顯示說明的指令以及使用 -v 選項來顯示產品版本的指令除外。

指定使用者名稱

使用 -u 選項指定管理使用者名稱。如果省略使用者名稱，指令會提示您輸入。例如，下列指令會顯示預設代理程式的相關資訊：

imqcmd query bkr -u admin

為了方便您閱讀，本章範例中 -u 選項的引數都顯示預設使用者名稱 admin。在生產環境中應該使用自訂使用者名稱。

指定密碼

您可以使用下列任一方法指定密碼：

• 建立密碼檔案 (passfile)，將密碼輸入該檔案中。在指令行中使用 -passfile 選項，提供密碼檔案名稱。

• 讓指令提示您輸入密碼。

舊版 Message Queue 可讓您在 imqcmd 指令行上使用 -p 選項來指定密碼。此選項已經停用，將從未來的版本中移除。

指定代理程式名稱和連接埠

imqcmd 的預設代理程式是本地主機上執行的代理程式，預設連接埠是 7676。

對遠端主機上執行的代理程式或非預設連接埠上偵聽的代理程式下達指令時，必須使用 -b 選項來指定代理程式的主機和連接埠。

範例

本小節中的範例說明如何使用 imqcmd。

第一個範例列出在使用連接埠 7676 的 localhost 上執行的代理程式特性，因此不需要 -b 選項。指令使用預設管理使用者名稱 (admin ) 並且省略密碼，因此指令會提示您輸入密碼。

imqcmd query bkr -u admin

下列範例會列出在使用連接埠 1564 的主機 myserver 上執行的代理程式特性。使用者名稱是 aladdin。(若要讓此指令可以運作，需要更新使用者儲存庫，並將使用者名稱 aladdin 增加至 admin 群組中。)

imqcmd query bkr -b myserver:1564 -u aladdin

下列範例列出在使用連接埠 7676 的 localhost 上執行的代理程式特性。該指令的初始逾時設定為 20 秒，重試 (逾時後) 次數設定為 7。使用者密碼位於 myPassfile 密碼檔案中，該檔案位於呼叫指令時所在的目前目錄中。

imqcmd query bkr -u admin -passfile myPassfile -rtm 20 -rtr 7

如果您要與代理程式使用安全連線，可以在範例中使用 -secure 選項。-secure 選項會讓 imqcmd 使用已經配置並啟動的 ssladmin 服務。

顯示代理程式資訊

若要查詢並顯示單一代理程式的相關資訊，請使用 query bkr 子指令。

query bkr 子指令的語法如下：

imqcmd query bkr -b hostName:
portNumber

該子指令會列出預設代理程式或指定主機和連接埠上的代理程式之特性目前的設定。它也會顯示連線到指定代理程式的執行中代理程式 (在多代理程式叢集中) 清單。

例如：

imqcmd query bkr -u admin

提示您輸入密碼後，指令會輸出類似下列的內容：

Version                                              3.6
Instance Name                                        imqbroker
Primary Port                                         7676
                                                   
Current Number of Messages in System                 0
Current Total Message Bytes in System                0

Current Number of Messages in Dead Message Queue     0
Current Total Message Bytes in Dead Message Queue    0

Log Dead Messages                                    true
Truncate Message Body in Dead Message Queue          false
                                                   
Max Number of Messages in System                     unlimited (-1)
Max Total Message Bytes in System                    unlimited (-1)
Max Message Size                                     70m
                                                   
Auto Create Queues                                   true
Auto Create Topics                                   true
Auto Created Queue Max Number of Active Consumers    1
Auto Created Queue Max Number of Backup Consumers    0
                                                   
Cluster Broker List (active)                         
Cluster Broker List (configured)                     
Cluster Master Broker                                
Cluster URL                                          
                                                   
Log Level                                            INFO
Log Rollover Interval (seconds)                      604800
Log Rollover Size (bytes)                            unlimited (-1)

更新代理程式特性

您可以使用 update bkr 子指令更新下列代理程式特性：

• imq.autocreate.queue

• imq.autocreate.topic

• imq.autocreate.queue.maxNumActiveConsumers

• imq.autocreate.queue.maxNumBackupConsumers

• imq.cluster.url

• imq.destination.DMQ.truncateBody

• imq.destination.logDeadMsgs

• imq.log.level

• imq.log.file.rolloversecs

• imq.log.file.rolloverbytes

• imq.system.max_count

• imq.system.max_size

• imq.message.max_size

• imq.portmapper.port

update bkr 子指令的語法如下：

imqcmd update bkr [-b hostName:
portNumb er]-o attribute=value
 [[-o attribute=value1]
…]

該子指令變更預設代理程式或指定主機和連接埠上的代理程式的指定屬性。例如，以下指令會關閉佇列目標的自動建立功能：

imqcmd update bkr -o "imq.autocreate.queue=false" -u admin

第 14 章, 代理程式特性參照中描述這些特性。

暫停和重新繼續代理程式

啟動代理程式之後，您可以使用 imqcmd 子指令控制代理程式的狀態。

暫停代理程式

暫停代理程式會暫停代理程式的連線服務執行緒，這將導致代理程式停止偵聽連線連接埠。因此，代理程式將無法繼續接受新的連線、接收訊息或派送訊息。

但是，暫停代理程式不會暫停 admin 連線服務。此服務可讓您執行所需的管理作業，以管理代理程式的訊息流量。暫停代理程式也不會暫停 cluster 連線服務。但是，叢集中的訊息傳送會根據叢集中不同代理程式所執行的傳送功能而有差異。因此，暫停叢集中的代理程式可能會造成某些訊息流量變慢。

pause bkr 子指令的語法如下：

imqcmd pause bkr [-b hostName:
portNumber]

該指令會暫停預設代理程式或指定主機和連接埠上的代理程式。

以下指令會暫停連接埠 1588 上 myhost 執行的代理程式。

imqcmd pause bkr -b myhost:1588 -u admin

您也可以暫停個別連線服務和個別實體目標。如需更多資訊，請參閱暫停和重新繼續連線服務和暫停和重新繼續實體目標。

重新繼續代理程式

重新繼續代理程式會重新啟動代理程式的服務執行緒，而且此代理程式會重新繼續偵聽連接埠。

resume bkr 子指令的語法如下：

imqcmd resume bkr [-b hostName:
portNumber]

該子指令會重新繼續預設代理程式或指定主機和連接埠上的代理程式。

以下指令會重新繼續連接埠 7676 上 localhost 執行的代理程式。

imqcmd resume bkr -u admin

關閉和重新啟動代理程式

適當地關閉代理程式會終止代理程式程序。代理程式停止接受新的連線和訊息，它將完成現有訊息的傳送並終止代理程式程序。

shutdown bkr 子指令的語法如下：

imqcmd shutdown bkr [-b hostName:
portNumber]

該子指令會關閉預設代理程式或指定主機和連接埠上的代理程式。

以下指令會關閉連接埠 1572 上 ctrlsrv 執行的代理程式：

imqcmd shutdown bkr -b ctrlsrv:1572 -u admin

使用 restart bkr 子指令關閉和重新啟動代理程式。restart bkr 子指令的語法如下：

imqcmd restart bkr [-b hostName:
portNumber]

該子指令使用首次啟動代理程式時指定的選項，關閉預設代理程式或指定主機和連接埠上的代理程式，然後重新啟動。若要選擇其他選項，請關閉代理程式後再重新啟動，指定您要的選項。

顯示代理程式度量

若要顯示有關代理程式的度量資訊，請使用 metrics bkr 子指令。

metrics bkr 子指令的語法如下：

imqcmd metrics bkr [-b hostName:
portNumber]
       [-m metricType] [-int interval] [-msp 
numSamples]

該子指令顯示預設代理程式或指定主機和連接埠上的代理程式的代理程式度量。

您可以使用 -m 選項，指定下列一種要顯示的度量類型：

• ttl 顯示傳入和傳出代理程式的訊息和資料封包度量 (預設度量類型)。

• rts 顯示 (每秒) 傳入和傳出代理程式的訊息和資料封包流量速率度量。

• cxn 顯示連線、虛擬記憶體堆疊和執行緒。

使用 -int 選項，指定顯示度量的時間間隔 (以秒為單位)。預設為 5 秒鐘。

使用 -msp 選項，指定輸出中顯示的範例數目。預設的數目為沒有限制 (無限)。

例如，若要取得每 10 秒時間間隔，代理程式傳入與傳出的訊息速率，請使用：

imqcmd metrics bkr -m rts -int 10 -u admin

此指令的輸出如下：

--------------------------------------------------------
 Msgs/sec   Msg Bytes/sec   Pkts/sec    Pkt Bytes/sec   
 In   Out     In      Out     In   Out     In      Out  
--------------------------------------------------------
 0     0      27      56      0     0      38      66   
 10    0     7365     56      10    10    7457    1132  
 0     0      27      56      0     0      38      73   
 0     10     27     7402     10    20    1400    8459  
 0     0      27      56      0     0      38      73

如需有關代理程式收集和報告之資料的詳細說明，請參閱代理程式通用度量。

管理連線服務

imqcmd 公用程式包括允許您執行以下連線服務管理作業的子指令：

• 列出連線服務

• 顯示連線服務資訊

• 更新連線服務特性

• 顯示連線服務度量

• 暫停和重新繼續連線服務

代理程式支援來自應用程式用戶端和管理用戶端的連線。目前，Message Queue 代理程式可提供的連線服務如表 5–1 中所示。如表格中所示，每種服務都與使用的服務類型 (應用程式用戶端為 NORMAL，管理用戶端為 ADMIN) 和基本傳輸協定相關。

您可以使用 imqcmd 子指令來管理整個連線服務，或管理個別連線服務。如果子指令的目標是個別服務，請使用 -n 選項，以表 5–1 之 [服務名稱] 欄位中所列的其中一個名稱進行指定。

列出連線服務

若要列出代理程式上可用的連線服務，請使用 list svc 子指令。

list svc 子指令的語法如下：

imqcmd list svc [-b hostName:
portNumber]

該子指令列出預設代理程式或指定主機和連接埠上的代理程式上的所有連線服務。

以下指令列出在使用連接埠 7676 的 localhost 上所執行代理程式的所有服務：

imqcmd list svc -u admin

此指令將輸出以下資訊：

------------------------------------------------
Service Name    Port Number        Service State
------------------------------------------------
admin           41844 (dynamic)    RUNNING
httpjms         -                  UNKNOWN
httpsjms        -                  UNKNOWN
jms             41843 (dynamic)    RUNNING
ssladmin        dynamic            UNKNOWN
ssljms          dynamic            UNKNOWN

顯示連線服務資訊

若要查詢並顯示單一服務的相關資訊，請使用 query 子指令。

query svc 子指令的語法如下：

imqcmd query svc -n serviceName [-b 
hostName:portNumber]

query svc 子指令會顯示在預設代理程式或指定主機和連接埠的代理程式上，所執行的指定服務之相關資訊。

例如：

imqcmd query svc -n jms -u admin

提示輸入密碼後，指令會輸出類似下列的內容：

Service Name                           jms
Service State                          RUNNING
Port Number                            60920 (dynamic)
                                     
Current Number of Allocated Threads    0
Current Number of Connections          0
                                     
Min Number of Threads                  10
Max Number of Threads                  1000

更新連線服務特性

您可以使用 update 子指令，變更表 5–2 中所列出的一個或多個服務特性的值。

update 子指令的語法如下：

imqcmd update svc -n serviceName [-b 
hostName:portNumber] 
         -o attribute=value [-o 
attribute=value1]…

該子指令更新在預設代理程式或指定主機和連接埠上的代理程式上執行的指定服務的指定屬性。如需服務屬性的描述，請參閱連線特性。

以下指令將指定給 jms 服務的執行緒最小數目變更為 20。

imqcmd update svc -n jms -o “minThreads=20” -u admin

顯示連線服務度量

若要顯示有關單一服務的度量資訊，請使用 metrics 子指令。

metrics 子指令的語法如下：

imqcmd metrics svc -n serviceName [-b 
hostName:portNumber] [-m metricType
]
     [-int interval] [-msp numSamples]

該子指令顯示預設代理程式或指定主機和連接埠上的代理程式上的指定服務之度量。

使用 -m 選項指定要顯示的度量類型：

• ttl 顯示經由指定連線服務，傳入和傳出代理程式的訊息和資料封包的度量。(預設度量類型)。

• rts 顯示經由指定連線服務，(每秒) 傳入和傳出代理程式的訊息和資料封包流量速率度量。

• cxn 顯示連線、虛擬記憶體堆疊和執行緒。

使用 -int 選項，指定顯示度量的時間間隔 (以秒為單位)。預設為 5 秒鐘。

使用 -msp 選項，指定輸出中顯示的範例數目。預設的數目為沒有限制 (無限)。

例如，若要取得由 jms 連線服務處理的訊息和資料封包等累計總數，請使用：

imqcmd metrics svc -n jms -m ttl -u admin

提示輸入密碼後，指令會輸出類似下列的內容：

-------------------------------------------------
  Msgs      Msg Bytes      Pkts      Pkt Bytes   
In   Out    In     Out   In   Out    In     Out  
-------------------------------------------------
164  100  120704  73600  282  383  135967  102127
657  100  483552  73600  775  876  498815  149948

如需有關使用 imqcmd 以報告連線服務度量的更多詳細描述，請參閱連線服務度量。

暫停和重新繼續連線服務

除 admin 服務無法暫停之外，若要暫停其他任何服務，請使用 pause svc 和 resume svc 子指令。

pause svc 子指令的語法如下：

imqcmd pause svc -n serviceName [-b 
hostName:portNumber]

該子指令暫停在預設代理程式或指定主機和連接埠上代理程式執行的指定服務。 例如，下列指令會暫停預設代理程式上執行的 httpjms 服務。

imqcmd pause svc -n httpjms -u admin

暫停服務會造成以下影響：

• 代理程式會停止接受暫停服務上的新用戶端連線。如果 Message Queue 用戶端嘗試開啟新的連線，將會發生異常。

• 暫停服務上的所有現有連線會維持持續作用狀態，但在重新繼續服務前，代理程式會暫停此類連線上的所有訊息處理。(例如，如果用戶端嘗試傳送訊息，在重新繼續服務前，send 方法會阻斷此訊息。)

• 將會維護任何已被代理程式接收之訊息的訊息傳送狀態。(例如，作業事件不會中斷，並且會在重新繼續服務後，繼續訊息傳送。)

若要重新繼續服務，請使用 resume svc 子指令。

resume svc 子指令的語法如下：

imqcmd resume svc -n serviceName[-b 
hostName:portNumber]

該子指令會重新繼續在預設代理程式或指定主機和連接埠上代理程式執行的指定服務。

取得有關連線的資訊

imqcmd 公用程式包括可讓您列出和取得連線相關資訊的子指令。

list cxn 子指令列出指定服務名稱的所有連線。list cxn 子指令的語法如下：

imqcmd list cxn [-svn serviceName] [-b 
hostName:portNumber]

該子指令列出預設代理程式上指定服務名稱的所有連線，或指定主機和連接埠上代理程式上的所有連線。 如果未指定服務名稱，則會列出所有連線。

例如，下列指令會列出預設代理程式上的所有連線：

imqcmd list cxn -u admin

提示輸入密碼後，指令會輸出類似下列的內容：

Listing all the connections on the broker specified by:
-----------------------------------
Host                   Primary Port
------------------------------------
localhost              7676

---------------------------------------------------------------------------
Connection ID         User    Service   Producers  Consumers    Host
---------------------------------------------------------------------------
1964412264455443200   guest   jms       0          1            127.0.0.1
1964412264493829311   admin   admin     1          1            127.0.0.1

Successfully listed connections.

若要查詢並顯示單一服務的相關資訊，請使用 query 子指令。

query cxn -n connectionID [-b 
hostName:portNumber]

該子指令顯示在預設代理程式或指定主機和連接埠之代理程式上指定連線的相關資訊。

例如：

imqcmd query cxn -n 421085509902214374 -u admin

提示輸入密碼後，指令會輸出類似下列的內容：

Connection ID      421085509902214374
User               guest
Service            jms
Producers          0
Consumers          1
Host               111.22.333.444
Port               60953
Client ID          
Client Platform    

管理長期訂閱

使用 imqcmd 子指令，您可以透過下列一項或多項作業，來管理代理程式的長期訂閱：

• 列出長期訂閱

• 清除長期訂閱的所有訊息

• 銷毀長期訂閱

長期訂閱是由用戶端註冊為長期的主題訂閱；它具有唯一的身份，並要求代理程式保留此訂閱的訊息 (即使它的用戶成為非使用中的用戶)。通常，代理程式僅在為長期訂閱者保留的訊息過期時，才刪除該訊息。

若要列出指定實體目標的長期訂閱，請使用 list dur 子指令。list dur 子指令的語法如下：

imqcmd list dur -d destName

例如，下列指令使用本地主機預設連接埠上執行的代理程式，列出主題 SPQuotes 的所有長期訂閱：

imqcmd list dur -d SPQuotes

對於主題的每個長期訂閱，list dur 子指令會傳回長期訂閱的名稱、使用者的用戶端 ID、在此主題上形成佇列的訊息數目，以及長期訂閱的狀態 (使用中/非使用中)。例如：

Name        Client ID       Number of   Durable Sub
                            Messages      State
----------------------------------------------------------------
myDurable   myClientID       1           INACTIVE

您可以使用從 list dur 子指令傳回的資訊，識別您可能要銷毀或要為其清除訊息的長期訂閱。

purge dur 子指令使用指定的用戶端識別碼，清除指定長期訂閱的所有訊息。purge dur 子指令的語法如下：

imqcmd purge dur -n subscrName -c 
clientID

destroy dur 子指令使用指定的用戶端識別碼，銷毀指定的長期訂閱。destroy dur 子指令的語法如下：

imqcmd destroy dur -n subscrName -c 
clientID

例如，下列指令會銷毀長期訂閱 myDurable 和 clientID myClientID。

imqcmd destroy dur -n myDurable -c myClientID

管理作業事件

由用戶端應用程式啟動的所有作業事件可由代理程式追蹤。這些作業事件可以是簡單的 Message Queue 作業事件，也可以是分散式作業事件 (XA 資源) 管理員所管理的分散式作業事件。

每個作業事件都有 Message Queue 作業事件 ID：代理程式上可用來唯一識別作業事件的 64 位元號碼。分散式作業事件另有由分散式作業事件管理程式指定的分散式作業事件 ID (XID)，此 ID 長達 128 個位元組。Message Queue 會維護 Message Queue 作業事件 ID 與 XID 的關聯。

如果發生故障，分散式作業事件很可能一直處於 PREPARED 狀態，而不會被確定。因此，作為管理員，您可能需要監視作業事件，然後回復或確定處於準備狀態的作業事件。

若要列出代理程式追蹤的所有作業事件，請使用 list txn 指令。list tx 子指令的語法如下：

imqcmd list txn

例如，以下指令會列出代理程式中的所有作業事件。

imqcmd list txn

對於每個作業事件，list 子指令會傳回作業事件 ID、狀態、使用者名稱、訊息或確認的數目，以及建立時間。例如：

---------------------------------------------------------------
Transaction ID  State    User name   # Msgs/   Creation time
                                     # Acks
---------------------------------------------------------------

64248349708800  PREPARED  guest      4/0      1/30/02 10:08:31 AM
64248371287808  PREPARED  guest      0/4      1/30/02 10:09:55 AM

此指令顯示代理程式中的所有本機作業事件和分散式作業事件。您僅能確定或回復處於 PREPARED 狀態的作業事件。如果您知道由於故障使作業事件處於此狀態，並且此作業事件未處於由分散式作業事件管理程式確定的過程中，您應確定或回復此作業事件。

例如，如果代理程式的自動回復特性設定為 false (請參閱表 14–2)，則您必須在啟動代理程式時，手動確定或回復處於 PREPARED 狀態的作業事件。

list 子指令也顯示在作業事件中產生的訊息數目，以及在作業事件中確認的訊息數目 (#Msgs/#Acks) 。這些訊息不會被傳送，並且確認也不會被處理，直至作業事件被確定。

query 子指令可讓您查閱相同的資訊，以及一些其他值：用戶端 ID、連線識別，以及分散式作業事件 ID (XID)。query txn 子指令的語法如下：

imqcmd query txn -n transactionID

例如，下列範例的輸出內容如下：

imqcmd query txn -n 64248349708800

Client ID
Connection                 guest@192.18.116.219:62209->jms:62195
Creation time              1/30/02 10:08:31 AM
Number of acknowledgments 0
Number of messages         4
State                      PREPARED
Transaction ID             64248349708800
User name                  guest
XID
6469706F6C7369646577696E6465723130313234313431313030373230

使用 commit 和 rollback 子指令，確定或回復分散式作業事件。如前所述，僅可確定或回復處於 PREPARED 狀態的作業事件。

commit 子指令的語法如下：

imqcmd commit txn -n transactionID

例如：

imqcmd commit txn -n 64248349708800

rollback 子指令的語法如下。子指令：

imqcmd rollback txn -n transactionID

如需更多資訊，請參閱表 14–2 中的 imq.transaction.autorollback 特性。

還可配置代理程式，以便在啟動代理程式時自動回復處於 PREPARED 狀態的作業事件。

第 6 章 管理實體目標

本章說明如何使用 imqcmd 公用程式，管理實體目標。Message Queue^TM 訊息可以經由代理程式上的實體目標，路由至其使用者用戶端。代理程式會管理實體目標的相關記憶體和永久性存放區，並且設定其運作方式。

在代理程式叢集中，您只要在一個代理程式上建立實體目標，叢集會將此實體目標傳播至所有代理程式。應用程式用戶端可以訂閱或使用叢集中任何代理程式上的主題或佇列，因為代理程式會合作跨叢集路由訊息。但是唯有產生訊息的原始代理程式，可以管理訊息的永久性和確認。

本章涵蓋下列主題：

• 使用指令公用程式

• 建立實體目標

• 列出實體目標

• 顯示實體目標資訊

• 更新實體目標特性

• 暫停和重新繼續實體目標

• 清除實體目標

• 銷毀實體目標

• 壓縮實體目標

• 使用停用的訊息佇列

表 13–5 提供有關使用 imqcmd 子指令來管理實體目標並且完成這些工作的完整參考資訊。

如需實體目標的簡介，請參閱「Message Queue 技術摘要」。

用戶端應用程式與實體目標互動時，會使用 Destination 物件。為了提供者獨立性和可移植性，用戶端通常使用管理員建立的目標物件，即目標管理物件。您可以配置供用戶端應用程式使用的受管理物件，如第 8 章, 管理受管理物件所述。

使用指令公用程式

使用 Message Queue 指令公用程式 (imqcmd) 管理實體目標。imqcmd 指令的語法，與您將其用於管理其他代理程式服務時相同。

如需有關 imqcmd、其子指令和選項的參考資訊，請參閱第 13 章, 指令行參照。

子指令

表 6–1 列出本章描述的 imqcmd 子指令用法。如需有關這些子指令的參考資訊，請參閱實體目標管理。

建立實體目標

若要建立實體目標，請使用 imqcmd create 子指令。create 子指令的語法如下：

create dst -t destType -n 
destName [-o property=value
] [-o property=value1]
…

例如，若要建立佇列目標，請輸入以下指令：

imqcmd create dst -n myQueue -t q -o “maxNumActiveConsumers=5”

若要建立主題目標，請輸入以下指令：

imqcmd create dst -n myTopic -t t -o “maxBytesPerMsg=5000”

建立實體目標時，您必須指定以下項目：

• 實體目標類型 t (topic) 或 q (queue)。

• 實體目標名稱。命名規則如下：

  • 名稱只能使用字母數字字元。不能包含空格。

  • 名稱可以用英文字母字元、底線字元 (_) 或錢幣符號 ($) 開頭。不能以 mq 字元字串開頭。

  實體目標特性的非預設值。

更新實體目標時，您也可以設定特性。

很多實體目標特性都會影響代理程式記憶體資源和訊息流量。例如，您可以指定能夠傳給實體目標的產生器數目、產生器可以傳送的訊息數量和容量，以及到達實體目標限制時代理程式的回應方式。這些限制類似於代理程式配置特性所控制的一切代理程式限制。

下列特性可用於佇列目標和主題目標：

• maxNumMsgs：指定實體目標中允許未使用訊息的最大數目。

• maxTotalMsgBytes：指定實體目標中允許給未使用訊息的最大總記憶體容量 (以位元組為單位)。

• limitBehavior：指定達到記憶體限制執行緒時，代理程式回應的方式。

• maxBytesPerMsg：指定實體目標中允許的單一訊息最大容量 (以位元組為單位)。

• maxNumProducers：指定實體目標中產生器的最大數目。

• consumerFlowLimit：指定單一批次中，傳送給用戶的最大訊息數目。

• isLocalOnly：僅適用於代理程式叢集。指定在其他代理程式上不複製實體目標，且限制實體目標僅傳送訊息給本機用戶 (即連線到已建立實體目標之代理程式的用戶)。

• useDMQ：指定捨棄實體目標之停用的訊息或放到停用的訊息佇列中。

下列特性僅用於佇列目標：

• maxNumActiveConsumers：指定從佇列目標之負載平衡傳送中可成為使用中用戶的最大數目。

• maxNumBackupConsumers：指定最大備份用戶數目，如果無法從佇列目標進行負載平衡傳送，則這些用戶可以取代使用中用戶。

• localDeliveryPreferred：僅適用於代理程式叢集中的負載平衡佇列傳送。如果本機代理程式沒有用戶，則指定訊息僅傳送給遠端用戶。

如需有關實體目標特性的完整參考資訊，請參閱第 15 章, 實體目標特性參照。

針對自動建立的目標，請在代理程式實例配置檔案中設定預設特性值。表 14–3 中有自動建立特性的參考資訊。

列出實體目標

您可以取得關於實體目標目前特性值的相關資訊、關於與實體目標相關之產生器或用戶的數目以及關於訊息傳送度量的資訊，例如實體目標中訊息的數目和容量。

若要尋找實體目標以便取得其相關資訊，請使用 list dst 子指令，列出代理程式上的所有實體目標。list dst 子指令的語法如下：

list dst [-t destType] [-tmp]

該指令可以列出所指定類型的實體目標。目標類型值 (-t) 的選項可為 q (佇列) 或 t (主題)。

如果省略目標類型，則會列出所有類型的實體目標。

list dst 子指令可選擇性指定要列出的目標類型，或包括暫時目標 (使用 -tmp 選項)。用戶端建立的暫時目標，通常用來接收傳送到其他用戶端的訊息回應。

例如，若要取得連接埠 4545 上 myHost 執行的代理程式的所有實體目標，請輸入以下指令：

imqcmd list dst -b myHost:4545

除非您指定目標類型 t 只包含主題，否則除了其他實體目標，也一定會顯示停用的訊息佇列 mq.sys.dmq 之資訊。

顯示實體目標資訊

若要取得實體目標的目前特性，請使用 query dst 子指令。query dst 子指令的語法如下：

query dst -t destType -n 
destName

該指令列出指定類型和名稱之目標的相關資訊。例如，下列指令會顯示佇列目標 XQueue 的相關資訊：

imqcmd query dst -t q -n XQueue -u admin

此指令的輸出如下：

------------------------------------
Destination Name    Destination Type
------------------------------------
XQueue              Queue

On the broker specified by:

-------------------------
Host         Primary Port
-------------------------
localhost    7676

Destination Name                      XQueue
Destination Type                      Queue
Destination State                     RUNNING
Created Administratively              true

Current Number of Messages            0
Current Total Message Bytes           0
Current Number of Producers           0
Current Number of Active Consumers    0
Current Number of Backup Consumers    0

Max Number of Messages                unlimited (-1)
Max Total Message Bytes               unlimited (-1)
Max Bytes per Message                 unlimited (-1)
Max Number of Producers               100
Max Number of Active Consumers        1
Max Number of Backup Consumers        0

Limit Behavior                        REJECT_NEWEST
Consumer Flow Limit                   1000
Is Local Destination                  false
Local Delivery is Preferred           false
Use Dead Message Queue                true

輸出也會顯示與目標相關之產生器與用戶的數目。佇列目標的這個數目包含使用中用戶和備份用戶。

您可以使用 update dst 子指令來變更一個或多個特性值 (請參閱更新實體目標特性)。

更新實體目標特性

透過使用 update dst 子指令和 -o 選項指定要更新的特性，您可以變更實體目標的特性。update bkr 子指令的語法如下：

update dst -t destType -n 
destName -o property=value [[-o 
property=value1]…]

該指令會更新指定目標上的指定特性的值。 特性名稱可以是表 15–1 中所列出的任何特性。

您可以多次使用 -o 選項，更新多個特性。例如，以下指令將 maxBytesPerMsg 特性變更為 1000，並將 MaxNumMsgs 特性變更為 2000：

imqcmd update dst -t q -n myQueue -o “maxBytesPerMsg=1000”
              -o “maxNumMsgs=2000” -u admin

請參閱第 15 章, 實體目標特性參照，以獲得可以更新的特性清單。

您無法使用 update dst 子指令更新實體目標的類型，或更新 isLocalOnly 特性。

停用的訊息佇列是特殊的實體目標，其特性與其他目標的特性不同。如需更多資訊，請參閱使用停用的訊息佇列。

暫停和重新繼續實體目標

您可以暫停實體目標，以便控制從產生器傳送訊息到目標，或從目標傳送訊息到用戶，或同時控制上述兩個動作。要特別注意的是，您可以暫停進入目標的訊息流量，以避免目標在訊息產生速度高於使用速度時收到過多訊息。壓縮實體目標之前，必須先暫停該目標。

若要暫停傳送到實體目標的訊息或暫停從實體目標傳送的訊息，請使用 pause dst 子指令。pause dst 子指令的語法如下：

pause dst [-t destType -n 
destName] [-pst pauseType]

針對指定類型和名稱的目標，該子指令可以暫停至用戶的訊息傳送 (-pst CONSUMERS)，或暫停來自產生器的訊息傳送 (-pst PRODUCERS)，或者兩者皆暫停 (-pst ALL)。如果沒有指定目標類型與名稱，則會暫停所有實體目標。預設為 ALL。

範例：

imqcmd pause dst -n myQueue -t q -pst PRODUCERS -u admin
imqcmd pause dst -n myTopic -t t -pst CONSUMERS -u admin

若要重新繼續向暫停的目標傳送，請使用 resume dst 子指令。resume dst 子指令的語法如下：

resume dst [-t destType -n 
destName]

該子指令重新繼續向指定類型和名稱之暫停目標傳送訊息。如果沒有指定目標類型與名稱，則會重新繼續所有目標。

範例：

imqcmd resume dst -n myQueue -t q

在代理程式叢集中，實體目標實例會常駐在叢集中的每個代理程式。必須予以個別暫停。

清除實體目標

您可以清除目前在實體目標上形成佇列的所有訊息。清除實體目標即表示會刪除儲存於該目標的所有訊息。

當累積的訊息佔用太多的系統資源時，您可能需要清除訊息。當佇列沒有註冊的用戶用戶端並要接收許多訊息時，可能需要清除訊息。如果非使用中的主題長期訂閱者未成為使用中訂閱者，也可能需要清除訊息。在這兩種情況下，沒有必要保留訊息。

若要清除實體目標上的訊息，請使用 purge dst 子指令。purge dst 子指令的語法如下：

purge dst -t destType -n 
destName

此子指令會清除實體目標上指定類型與名稱的訊息。

範例：

imqcmd purge dst -n myQueue -t q -u admin
imqcmd purge dst -n myTopic -t t -u admin

如果已關閉代理程式，並且不想在其重新啟動時傳送舊的訊息，請使用 -reset messages 選項清除舊的訊息，例如：

imqbrokerd -reset messages -u admin

這可避免重新啟動代理程式後清除目標的麻煩。

在代理程式叢集中，實體目標實例會常駐在叢集中的每個代理程式。您必須個別清除這些目標。

銷毀實體目標

若要銷毀實體目標，請使用 destroy dst 子指令。destroy dst 子指令的語法如下：

destroy dst -t destType -n 
destName

此子指令會銷毀指定類型與名稱的實體目標。

範例：

imqcmd destroy dst -t q -n myQueue -u admin

銷毀實體目標會清除此目標上的所有訊息，並從代理程式中移除此目標；此作業不可復原。

您不能銷毀停用的訊息佇列。

壓縮實體目標

如果您使用檔案式資料存放區作為訊息的永久性存放區，即可監視磁碟使用，並於需要時壓縮磁碟。

檔案式訊息存放區的結構方式，是讓訊息可以儲存在與收納訊息之實體目標相對應的目錄中。在各個實體目標的目錄中，大部分訊息會儲存在一個檔案中，該檔案由大小不定的記錄所組成。(若要減少分段程序，大小超過可配置臨界值的訊息會儲存在其個別的檔案中。)

因為會存留不同大小的訊息，接著從記錄檔移除這些訊息，所以檔案中可能會產生空白片段，且將無法再重新使用這些可用記錄。

若要管理未使用的可用記錄，使用率下降時，指令公用程式包括每個實體目標監視磁碟使用及收回可用磁碟空間的子指令。

監視實體目標的磁碟使用

若要監視實體目標的磁碟使用，請使用下列指令：

imqcmd metrics dst -t q -n myQueue -m dsk -u admin

此指令的輸出如下：

--------------------------------------
Reserved   Used      Utilization Ratio
--------------------------------------
806400     804096    99
1793024    1793024   100
2544640    2518272   98

子指令輸出中的欄有下列涵義：

收回未使用的實體目標磁碟空間

磁碟使用模式依使用特定實體目標之訊息傳送應用程式的特徵而異。根據傳入和傳出實體目標的相關訊息流量和相關的訊息容量，保留的磁碟空間可能會不斷增加。

如果訊息產生速率大於訊息使用速率，那麼通常會重新使用可用記錄，且使用率應較高。但是，如果訊息產生速率與訊息使用速率相似或小於訊息使用速率，那麼使用率會比較低。

一般而言，您會穩定保留的磁碟空間並保持高使用率。通常如果系統到達穩定狀態 (即保留的磁碟空間大致固定)，並且使用率高 (高於 75%)，則不需要收回未使用的磁碟空間。如果系統到達穩定狀態且使用率低 (低於 50%)，您可以壓縮磁碟，收回可用記錄佔用的磁碟空間。

compact dst 子指令可用來壓縮資料存放區。compact dst 子指令的語法如下：

compact dst [-t destType -n 
destName]

此子指令會壓縮指定類型與名稱之實體目標的檔案式資料存放區。如果沒有指定目標類型與名稱，則會壓縮所有目標。必須在壓縮目標前暫停實體目標。

如果保留的磁碟空間不斷增加，請藉由設定目標記憶體限制特性和限制運作方式，重新配置目標的記憶體管理 (請參閱表 15–1)。

收回未使用的實體目標磁碟空間

1. 暫停目標。

   imqcmd pause dst -t q -n myQueue -u admin

2. 壓縮磁碟。

   imqcmd compact dst -t q -n myQueue -u admin

3. 重新繼續實體目標。

   imqcmd resume dst -t q -n myQueue -u admin

   如果未指定目標類型和名稱，則會在所有實體目標上執行這些作業。

使用停用的訊息佇列

停用的訊息佇列 mq.sys.dmq 是系統建立的實體目標，保留代理程式和其他實體目標之停用的訊息。停用的訊息佇列是用來監視、調校系統效率以及疑難排解的工具。如需「停用的訊息」一詞的定義和停用的訊息佇列之詳細資訊，請參閱「 Message Queue 技術摘要」。

代理程式啟動時會自動建立停用的訊息佇列。代理程式將無法處理或到期的訊息放在此佇列中。此外，其他實體目標可以使用停用的訊息佇列來保留已捨棄的訊息。使用停用的訊息佇列提供的資訊，有助於系統的疑難排解。

配置使用停用的訊息佇列

依預設，系統會配置實體目標以使用停用的訊息佇列。您可以設定實體目標特性 useDMQ，讓實體目標使用或不使用停用的訊息佇列。

下列範例建立的佇列 myDist，依預設使用停用的訊息佇列：

imqcmd create dst -n myDist -t q

下列範例讓相同的佇列停用此停用的訊息佇列：

imqcmd update dst -n myDist -t q -o useDMQ=false

設定 imq.autocreate.destination.useDMQ 代理程式特性，可以讓代理程式上所有自動建立的實體目標使用或不使用停用的訊息佇列。

管理停用的訊息佇列

您可使用 Message Queue 指令公用程式 (imqcmd) 管理停用的訊息佇列，方式與管理其他佇列僅有些微差異。例如，因為停用的訊息佇列是系統所建立的，因此您不能建立、暫停或銷毀它。此外，如表 6–3 中所示，停用的訊息佇列之預設值，有時會和正常佇列的預設值不相同。

停用的訊息佇列特性

您可以使用配置其他佇列的方式來配置停用的訊息佇列，但是有些實體目標特性可能不適用或是預設值不同。表 6–3 列出的佇列特性，會由停用的訊息佇列以特殊方式處理。

訊息內容

代理程式可以將整個訊息放入停用的訊息佇列中，或是捨棄訊息內文的內容，只保留標頭和特性資料。依預設，停用的訊息佇列儲存整個訊息。

若想要降低停用的訊息佇列容量，且不打算復原停用的訊息，請考慮將 imq.destination.DMQ.truncateBody 代理程式特性設為 true：

imqcmd update bkr -o imq.destination.DMQ.truncateBody=true

如此將會捨棄訊息本文，而只保留標頭與特性資料。

啟用停用的訊息之記錄功能

依預設，不記錄停用的訊息。啟用停用的訊息之記錄功能，可讓代理程式記錄下列事件：

• 代理程式將訊息移至停用的訊息佇列

• 代理程式捨棄來自停用的訊息佇列之訊息，以及不使用停用的訊息佇列之任何實體目標的訊息

• 實體目標達其上限

下列指令會啟用停用的訊息之記錄功能：

imqcmd update bkr -o imq.destination.logDeadMsgs=true

停用的訊息之記錄功能套用於所有使用停用的訊息佇列的實體目標。您不能啟用或停用個別實體目標的記錄功能。

第 7 章 管理安全性

您可透過下列方式管理安全性：配置使用者儲存庫以對使用者進行認證、定義存取控制、配置安全通訊端層 (SSL) 連線服務以對用戶端與代理程式間的通訊進行加密，以及設定用於啟動代理程式的密碼檔案。

本章包含下列各節：

• 使用者認證

• 使用者授權：存取控制特性檔案

• 訊息加密

• 密碼檔案

• 稽核記錄

使用者認證

當使用者嘗試連線至代理程式時，此代理程式將檢查使用者提供的名稱和密碼，以便進行認證。如果名稱和密碼與配置每個代理程式要參考的特定代理程式使用者儲存庫中的名稱和密碼相符，則代理程式承認此連線。

您負責維護使用者儲存庫中的使用者清單、使用者群組清單以及使用者密碼清單。您可以在每個代理程式實例使用不同的使用者儲存庫。本節介紹如何建立、寫入和管理儲存庫。

儲存庫可能是下列任一類型：

• Message Queue^TM 隨附的平面檔案儲存庫

  這種類型的使用者儲存庫使用非常容易。您可以使用使用者管理員公用程式 (imqusermgr) 寫入和管理此儲存庫。若要啟用認證，您應在使用者儲存庫中寫入每個使用者的名稱、密碼以及使用者群組名稱。

  如需設定與管理使用者儲存庫的更多資訊，請參閱使用平面檔案使用者儲存庫。

• LDAP 伺服器

  可以是使用 LDAP v2 或 v3 協定之現有或新的 LDAP 目錄伺服器。它不如平面檔案儲存庫易於使用，但是它可延展，因此更適用於生產環境。

  如果您要使用 LDAP 使用者儲存庫，可以利用 LDAP 供應商提供的工具來寫入和管理使用者儲存庫。如需更多資訊，請參閱將 LDAP 伺服器用於使用者儲存庫。

使用平面檔案使用者儲存庫

Message Queue 提供平面檔案使用者儲存庫和指令行工具，即使用者管理員公用程式 (imqusermgr)，您可以使用此工具寫入和管理平面檔案使用者儲存庫。以下各節描述平面檔案使用者儲存庫，以及您如何使用使用者管理員公用程式寫入和管理儲存庫。

建立使用者儲存庫

平面檔案使用者儲存庫是針對實例的。您啟動的每個代理程式實例，都會自動建立預設的使用者儲存庫 (稱為 passwd)。此使用者儲存庫的所在目錄名稱，與此儲存庫相關聯之代理程式實例名稱相同 (請參閱附錄 AMessage Queue^TM 資料的特定平台位置)：

   …/instances/instanceName/etc/passwd

此儲存庫在建立時就有兩個項目。表 7–1 的每一列表示一個項目。

這些初始項目可讓 Message Queue 代理程式在安裝之後立即使用，而無需管理員的介入：

• 初始 guest 使用者項目，可讓用戶端使用預設的 guest 使用者名稱和密碼，連線至代理程式實例。

• 初始 admin 使用者項目可讓您使用 imqcmd 指令和預設的 admin 使用者名稱和密碼來管理代理程式實例。您應該更新此初始項目以變更密碼 (請參閱變更預設管理員密碼)。

以下各節介紹如何寫入和管理平面檔案使用者儲存庫。

使用者管理員公用程式

Message Queue 使用者管理員公用程式 (imqusermgr) 可讓您編輯或寫入平面檔案使用者儲存庫。本節介紹使用者管理員公用程式。後續各節介紹如何使用 imqusermgr 子指令完成特定的工作。

如需 imqusermgr 指令的完整參考資訊，請參閱第 13 章, 指令行參照。

操作使用者管理員之前，請注意以下事項：

• 如果代理程式專用的使用者儲存庫不存在，您必須啟動對應的代理程式實例來建立儲存庫。

• 必須在安裝代理程式的主機上執行 imqusermgr 指令。

• 您必須擁有寫入儲存庫的適當權限：也就是說，在 Solaris 和 Linux 上，您必須是超級使用者或是第一個建立代理程式實例的使用者。

以下各節中的範例均假設為預設的代理程式實例。

子指令

imqusermgr 指令有子指令 add、delete、list 和 update。

• add 子指令可以將使用者和相關密碼增加到指定的 (或預設的) 代理程式實例儲存庫，並可選擇性指定使用者的群組。子指令語法如下：

  add [-i instanceName] -u userName -p passwd [-g group] [ -s]

• delete 子指令可以從指定的 (或預設的) 代理程式實例儲存庫刪除指定的使用者。子指令語法如下：

  delete [-i instanceName] -u userName [ -s] [-f]

• list 子指令可以顯示有關指定的 (或預設的) 代理程式實例儲存庫中，指定的使用者或所有使用者的資訊。子指令語法如下：

  list [ -i instanceName] [-u userName]

• update 子指令可以更新指定的 (或預設的) 代理程式實例儲存庫中，指定使用者的密碼和 (或) 狀態。子指令語法如下：

  update [ -i instanceName] -u userName -p passwd [ -a state] [-s] [ -f]

  update [-i instanceName] -u userName -a state [-p passwd] [-s] [-f]

指令選項

表 7–2 列出了 imqusermgr 指令的選項。

群組

為代理程式實例的使用者儲存庫增加使用者項目時，您可以指定三個預先定義群組中的任一項：admin、user 或 anonymous。如果未指定群組，則預設為指定群組 user。請遵照以下說明指定群組：

• admin 群組：用於代理程式管理員。依預設，已指定至此群組的使用者可以配置和管理代理程式。您可以將多個使用者指定給 admin 群組。

• user 群組：用於一般 (非管理) Message Queue 用戶端使用者。大多數用戶端使用者屬於 user 群組。依預設，此群組中的使用者可以產生訊息到所有主題與佇列、使用來自所有主題與佇列的訊息，以及瀏覽任何佇列中的訊息。

• anonymous 群組：用於不想使用代理程式知道的使用者名稱的 Message Queue 用戶端，可能是因為這些用戶端應用程式不知道應使用的實際使用者名稱。此帳號與大多數 FTP 伺服器中存在的匿名帳號類似。您一次僅可將一個使用者指定給 anonymous 群組。與 user 群組不一樣的是，您應當限制此群組的存取權限，或者應在部署時移除此群組中的使用者。

若要變更使用者的群組，您必須刪除此使用者項目，然後為此使用者增加其他項目，指定新的群組。

您不能將系統建立的群組重新命名或刪除，也不能建立新群組。但是，您可以指定用來定義群組成員可執行作業的存取規則。如需更多資訊，請參閱使用者授權：存取控制特性檔案。

使用者狀態

增加使用者至儲存庫時，使用者的狀態預設為使用中。若要讓此使用者變成非使用中狀態，您必須使用更新指令。例如，以下指令可讓使用者 JoeD 的狀態變成非使用中：

imqusermgr update -u JoeD -a false

已變成非使用中使用者的項目會保留在儲存庫中；但是，非使用中的使用者無法開啟新的連線。如果使用者為非使用中，且您新增具有相同名稱的其他使用者，則作業將失敗。您必須刪除非使用中使用者項目或變更新使用者的名稱，或者為新使用者命名其他名稱。這可防止您新增重複的使用者名稱。

使用者名稱與密碼的格式

使用者名稱與密碼必須遵循以下準則：

• 使用者名稱中不能包含星號 (*)、逗號 (,)、冒號 (:)、新行或換行字元。

• 使用者名稱或密碼必須至少包含一個字元。

• 如果使用者名稱或密碼包含空格，則必須將整個名稱或密碼括在引號內。

• 密碼或使用者名稱的長度沒有限制，除非指令 shell 對指令行上可輸入的最大字元數有所限制。

寫入和管理使用者儲存庫

使用 add 子指令可增加使用者至儲存庫。例如，以下指令可將使用者 Katharine 和密碼 sesame，增加到預設的代理程式實例使用者儲存庫。

imqusermgr add -u Katharine -p sesame -g user

使用 delete 子指令可從儲存庫刪除使用者。例如，以下指令可刪除使用者 Bob：

imqusermgr delete -u Bob

使用 update 子指令可變更使用者的密碼或狀態。例如，以下指令將 Katharine 的密碼變更為 aladdin：

imqusermgr update -u Katharine -p aladdin

若要列出有關一個或所有使用者的資訊，請使用 list 指令。以下指令顯示名為 isa 的使用者之相關資訊：

imqusermgr list -u isa

% imqusermgr list -u isa

User repository for broker instance: imqbroker
----------------------------------
User Name    Group    Active State
----------------------------------
isa          admin    true

以下指令列出所有使用者的相關資訊：

imqusermgr list

% imqusermgr list

User repository for broker instance: imqbroker
--------------------------------------
User Name    Group        Active State
--------------------------------------
admin        admin        true
guest        anonymous    true
isa          admin        true
testuser1    user         true
testuser2    user         true
testuser3    user         true
testuser4    user         false
testuser5    user         false

變更預設管理員密碼

為了安全性起見，您應將 admin 的預設密碼變更為只有您自己知道的密碼。以下指令將 mybroker 代理程式實例的預設管理員密碼 admin 變更為 grandpoobah。

imqusermgr update mybroker -u admin -p grandpoobah

當代理程式實例正在執行時，您可以透過執行任一指令行工具，以快速確認此變更是否生效。例如，下列指令會提示您提供密碼：

imqcmd list svc mybroker -u admin

輸入新密碼 (grandpoobah) 即生效，輸入舊密碼即失敗。

變更密碼後，使用任一 Message Queue 管理工具 (包括管理主控台) 時，您均應提供新的密碼。

將 LDAP 伺服器用於使用者儲存庫

若要將 LDAP 伺服器用於使用者儲存庫，請執行下列工作：

• 編輯實例配置檔案

• 設定管理員的存取控制

編輯實例配置檔案

若要代理程式使用目錄伺服器者，請在代理程式實例配置檔案 config.properties 中設定一些特性值。當使用者嘗試連線至代理程式實例或執行訊息傳送作業時，這些特性可讓代理程式實例查詢 LDAP 伺服器，以取得使用者和群組的相關資訊。

實例配置檔案位於代理程式實例目錄下的目錄中。路徑格式如下：

…/instances/instanceName

/props/config.properties

如需作業系統專用的實例目錄位置之詳細資訊，請參閱附錄 AMessage Queue^TM 資料的特定平台位置。

編輯配置檔案以使用 LDAP 伺服器

1. 透過設定以下特性，以指定您要使用 LDAP 使用者儲存庫：

   imq.authentication.basic.user_repository=ldap

2. 設定 imq.authentication.type 特性，以確定密碼應以 Base64 編碼 (basic) 還是以 MD5 編碼 (digest)，從用戶端傳送至代理程式。將 LDAP 目錄伺服器用於使用者儲存庫時，您必須將認證類型設定為 basic。例如：

   imq.authentication.type=basic

3. 您還必須設定可控制 LDAP 存取的代理程式特性。這些特性儲存在代理程式的實例配置檔案中。安全性服務中討論這些特性，安全性特性中也有摘要。

   Message Queue 使用 JNDI API 與 LDAP 目錄伺服器通訊。如需這些特性中所參考之語法和專有名詞的更多資訊，請參閱 JNDI 文件。Message Queue 使用 Sun JNDI LDAP 提供者和簡單認證。

   Message Queue 支援 LDAP 認證容錯移轉：您可以指定在進行認證時嘗試使用的 LDAP 目錄伺服器之清單 (請參閱 imq.user.repos.ldap.server 特性的參考資訊)。

   如需 LDAP 使用者儲存庫相關特性的設定範例，請參閱代理程式的 config.properties 檔案。

4. 如有必要，您需要編輯存取控制特性檔案中的使用者/群組和規則。如需使用存取控制特性檔案的更多資訊，請參閱使用者授權：存取控制特性檔案。

5. 如果在連線認證和群組搜尋期間，您要讓代理程式透過 SSL 與 LDAP 目錄伺服器通訊，則需要啟動 LDAP 伺服器中的 SSL，然後在代理程式配置檔案中設定以下特性：

   • 指定 LDAP 伺服器用於 SSL 通訊的連接埠。例如：

     imq.user_repository.ldap.server=myhost:7878

   • 將代理程式特性 imq.user_repository.ldap.ssl.enabled 設為 true。

     部署多台 LDAP 目錄伺服器時，請使用 ldap:// 指定其他每一台目錄伺服器。例如：

     imq.user_repository.ldap.server = myHost:7878 ldap:// otherHost:7878 …

     以空格分隔每一台目錄伺服器。清單中的所有目錄伺服器必須使用相同的值，以供其他與 LDAP 相關的特性使用。

設定管理員的存取控制

若要建立管理使用者，您可以使用存取控制特性檔案，指定可以建立 ADMIN 連線的使用者和群組。這些使用者和群組必須預先在 LDAP 目錄中定義。

任何使用者或群組只要能夠建立 ADMIN 連線，即可下達管理指令。

設定管理使用者

1. 將代理程式特性 imq.accesscontrol.enabled 設定為 true 預設值，啟用存取控制檔案。

   imq.accesscontrol.enabled 特性可以啟用存取控制檔案。

2. 開啟存取控制檔案 accesscontrol.properties。附錄 AMessage Queue^TM 資料的特定平台位置 中會列出此檔案的位置。

   此檔案包含一個項目，如下所示：

   service connection access control##################################connection.NORMAL.allow.user=*connection.ADMIN.allow.group=admin

   列出的項目僅為範例。請注意檔案式使用者儲存庫中有 admin 群組，但是依預設，LDAP 目錄中沒有此群組。您必須將 LDAP 目錄中已定義的群組名稱，替換為要授予 Message Queue 管理員權限的群組名稱。

3. 若要將 Message Queue 管理員權限授予使用者，請如下所示，輸入使用者名稱：

   connection.ADMIN.allow.user= userName[[,userName2] …]

4. 若要將 Message Queue 管理員權限授予群組，請如下所示，輸入群組名稱：

   connection.ADMIN.allow.group= groupName[[,groupName2] …]

使用者授權：存取控制特性檔案

存取控制特性檔案 (ACL 檔案) 包含的規則，指定使用者和群組使用者可以執行的作業。您可以編輯 ACL 檔案，限制某些使用者和群組執行作業。您可以在每個代理程式實例使用不同的 ACL 檔案。

無論使用者資訊放在平面檔案使用者儲存庫中還是放在 LDAP 使用者儲存庫中，均可使用 ACL 檔案。當用戶端應用程式執行以下作業時，代理程式會檢查其 ACL 檔案：

• 建立連線

• 建立產生器

• 建立用戶

• 瀏覽佇列

代理程式會檢查 ACL 檔案，判斷提出請求的使用者或該使用者所屬的群組，是否已有執行此作業的授權。

如果您編輯 ACL 檔案，新的設定會在下次代理程式檢查檔案以驗證授權時生效。您編輯此檔案後，不需要重新啟動代理程式。

建立存取控制特性檔案

不同實例有不同的 ACL 檔案。每次啟動代理程式實例時，會在實例目錄中建立預設檔案 accesscontrol.properties。此檔案的路徑格式如下 (請參閱附錄 AMessage Queue^TM 資料的特定平台位置)：

…/instances/brokerInstanceName/etc/accesscontrol.properties

ACL 檔案的格式與 Java 特性檔案的格式類似。先定義檔案的版本，然後分三部分指定存取控制規則：

• 連線存取控制

• 實體目標存取控制

• 實體目標自動建立存取控制

version 特性定義 ACL 特性檔案的版本；您不能變更此項目。

version=JMQFileAccessControlModel/100

以下說明存取規則的基本語法並介紹如何計算權限，之後描述可指定存取控制規則的 ACL 檔案三部分。

存取規則的語法

在 ACL 特性檔案中，存取控制會定義特定使用者或群組對受保護的資源 (如實體目標和連線服務) 擁有何種存取權。存取控制由一條或一組規則表示，每條規則皆以 Java 特性表示：

這些規則的基本語法如下：

resourceType.resourceVariant

.operation.access.
principalType=principals

表 7–3 描述了語法規則的元素。

以下為存取規則的一些範例：

• 以下規則表示任何使用者均可以將訊息傳送至名為 q1 的佇列。

  queue.q1.produce.allow.user=*

• 以下規則表示任何使用者均可以將訊息傳送至任何佇列。

  queue.*.produce.allow.user=*

若要指定非 ASCII 的使用者、群組或目標名稱，請使用 Unicode 換碼 (\\uXXXX) 表示法。如果您已經編輯並儲存具有非 ASCII 編碼名稱的 ACL 檔案，則可以使用 Java native2ascii 工具將其轉換為 ASCII。如需更多詳細資訊，請至

http://java.sun.com/j2se/1.4/docs/guide/intl/faq.html

如何計算權限

檔案中有多個存取規則時，權限計算如下：

• 特定存取規則置換一般存取規則。套用以下兩條規則之後，所有使用者均可以將訊息傳送至所有佇列，但是 Bob 卻無法將訊息傳送至 tq1。

  queue.*.produce.allow.user=*
  queue.tq1.produce.deny.user=Bob

• 賦予明確 principal 的存取權會置換賦予 * principal 的存取權。以下規則拒絕 Bob 產生訊息傳給 tq1，但允許其他所有使用者執行這項作業。

  queue.tq1.produce.allow.user=*
  queue.tq1.produce.deny.user=Bob

• 用於使用者的 * principal 規則置換用於群組的相應 * principal 規則。例如，以下兩條規則允許所有認證使用者將訊息傳送至 tq1。

  queue.tq1.produce.allow.user=*
  queue.tq1.produce.deny.group=*

• 授予使用者的存取權會置換授予使用者群組的存取權。在下列範例中，即使 Bob 是 User 成員，也無法產生訊息傳給 tq1。User 的所有其他成員皆可執行這項作業。

  queue.tq1.produce.allow.group=User
  queue.tq1.produce.deny.user=Bob

• 任何未透過存取規則明確授予的存取權限，都會遭到隱式拒絕。例如，如果 ACL 檔案不包含存取規則，則所有使用者都無法執行所有作業。

• 相同使用者或群組的拒絕和允許權限會相互抵銷。例如，以下兩條規則導致 Bob 無法瀏覽 q1：

  queue.q1.browse.allow.user=Bob
  queue.q1.browse.deny.user=Bob

  以下兩條規則導致 User 群組無法使用 q5 的訊息。

  queue.q5.consume.allow.group=User
  queue.q5.consume.deny.group=User

• 當存在多條相同的左側規則時，只有最後一項生效。

連線服務的存取控制

ACL 特性檔案中的連線存取控制區段，包含用於代理程式連線服務的存取控制規則。連線存取控制規則的語法如下：

connection.resourceVariant.
access.principalType=
principals

resourceVariant 定義有兩個值：NORMAL 和 ADMIN。您只能授權存取這些連線服務類型的預定值。

預設 ACL 特性檔案授權所有使用者存取 NORMAL 連線服務，並授權 admin 群組中的使用者存取 ADMIN 連線服務：

connection.NORMAL.allow.user=*
connection.ADMIN.allow.group=admin

如果您使用檔案式的使用者儲存庫，使用者管理員公用程式會建立預設群組 admin。如果您使用 LDAP 使用者儲存庫，只要執行下列一項作業即可使用預設 ACL 特性檔案：

• 在 LDAP 目錄中定義 admin 群組。

• 將 ACL 特性檔案中的 admin 名稱，換成 LDAP 目錄中已定義的一個或多個群組名稱。

您可以限制連線存取權限。例如，以下規則拒絕 Bob 存取 NORMAL，但是允許其他所有使用者進行存取：

connection.NORMAL.deny.user=Bob
connection.NORMAL.allow.user=*

您可以使用星號 (*) 字元代表所有認證使用者或群組。

對於檔案式使用者儲存庫和 LDAP 使用者儲存庫，使用 ACL 特性檔案授權存取 ADMIN 連線的方式有下列不同：

• 檔案式使用者儲存庫

  • 如果存取控制停用，admin 群組中的使用者有 ADMIN 連線權限。

  • 如果存取控制已啟用，請編輯 ACL 檔案。請明確授予使用者或群組存取 ADMIN 連線服務的權限。

• LDAP 使用者儲存庫。 如果您使用 LDAP 使用者儲存庫，請執行下列所有作業：

  • 啟用存取控制。

  • 編輯 ACL 檔案，並提供可以建立 ADMIN 連線的使用者或群組名稱。指定 LDAP 目錄伺服器中已定義的任何使用者或群組。

實體目標的存取控制

存取控制特性檔案的目標存取控制區段，包含實體目標型的存取控制規則。這些規則決定何人 (使用者/群組) 可以在何處 (實體目標) 做什麼 (作業)。這些規則所規定的存取權類型包括：將訊息傳送至佇列、將訊息發佈至主題、接收來自佇列的訊息、訂閱主題以及瀏覽佇列中的訊息。

依預設，任何使用者或群組對任何實體目標都擁有所有類型的存取權。您可以新增更多特定的目標存取規則，或編輯預設規則。本節的其餘部分介紹實體目標存取規則的語法，您必須理解此語法以編寫自己的規則。

目標規則的語法如下：

resourceType.resourceVariant.operation.access.principalType=principals

表 7–4 中有這些元素的描述：

可以將存取權賦予一個或多個使用者和 (或) 一個或多個群組。

以下範例說明了不同種類的實體目標存取控制規則：

• 允許所有使用者將訊息傳送至任何佇列目標。

  queue.*.produce.allow.user=*

• 拒絕群組 user 的任何成員訂閱主題 Admissions。

  topic.Admissions.consume.deny.group=user

自動建立實體目標的存取控制

ACL 特性檔案最後部分的存取規則，可以指定代理程式將為哪些使用者和群組自動建立實體目標。

當使用者在並不存在的實體目標上建立產生器或用戶時，如果已啟用代理程式的自動建立特性，則代理程式將會建立此目標。

依預設，任何使用者或群組均有權讓代理程式自動建立實體目標。此權限由以下規則指定：

queue.create.allow.user=*
topic.create.allow.user=*

您可以編輯 ACL 檔案以限制此類型的存取權。

實體目標自動建立存取規則的一般語法如下：

resourceType.create.access.principalType=principals

其中 resourceType 為 queue 或 topic。

例如，以下規則可讓代理程式為所有使用者 (除 Snoopy 之外) 自動建立主題目標。

topic.create.allow.user=*
topic.create.deny.user=Snoopy

請注意，實體目標自動建立規則的效果必須與實體目標存取規則的效果一致。例如，如果您 1) 變更目標存取規則，以禁止任何使用者將訊息傳送至目標，但是 2) 啟用目標的自動建立功能，如果此目標不存在，則代理程式將會建立此實體目標，但不會將訊息傳送至此目標。

訊息加密

本節說明如何設定以安全通訊端層 (SSL) 標準為基礎的連線服務，在用戶端和代理程式之間傳送加密訊息。Message Queue 支援下列 SSL 型連線服務：

• ssljms 服務使用 TCP/IP 傳輸協定，在用戶端和代理程式之間傳送安全、加密的訊息。

• ssladmin 服務使用 TCP/IP 傳輸協定，在 Message Queue 指令公用程式 (imqcmd) 和代理程式之間建立安全、加密的連線。管理主控台 (imqadmin) 不支援加密的連線。

• cluster 服務使用 TCP/IP 傳輸協定，為叢集中的代理程式之間提供安全、加密的通訊。

• httpsjms 服務使用 HTTPS 通道 Servlet 和 HTTP 傳輸協定，在用戶端和代理程式之間傳送安全、加密的訊息。

本節後續部分說明如何使用 ssljms、ssladmin 和 cluster 連線服務，透過 TCP/IP 設定安全連線。如需有關使用 httpsjms 服務，透過 HTTP 設定安全連線的詳細資訊，請參閱附錄 CHTTP/HTTPS 支援。

使用自我簽署的憑證

若要透過 TCP/IP 使用 SSL 型連線服務，您必須使用金鑰工具公用程式 (imqkeytool) 產生公開/私密金鑰對。此公用程式將公開金鑰內嵌於自我簽署的憑證中，此憑證將傳送至請求與代理程式連線的用戶端，此用戶端使用此憑證設定加密連線。本節描述如何使用此類自我簽署的憑證，設定 SSL 型服務。

若要提高認證層級，您可以使用憑證授權單位驗證的簽署憑證。相較於自我簽署的憑證，使用簽署憑證需要更多必要步驟。您必須先執行本節所述的步驟，接著執行使用簽署的憑證中的額外步驟。

Message Queue 支援具有自我簽署憑證的 SSL，會認為用戶端正與已知並可信任的伺服器通訊，而保護所傳送的資料。下列程序說明使用自我簽署的憑證設定 SSL 型連線服務的必要步驟。後續小節會詳細說明每個步驟。

使用自我簽署的憑證設定 SSL 型連線服務

1. 產生自我簽署的憑證。

2. 啟用代理程式中的 ssljms、ssladmin 或 cluster 連線服務。

3. 啟動代理程式。

4. 配置並執行用戶端。

   這個步驟僅適用於 ssljms 連線服務，不適用於 ssladmin 或 cluster。

產生自我簽署的憑證

執行金鑰工具公用程式 (imqkeytool)，為代理程式產生自我簽署的憑證。(在 UNIX® 系統上，需要以超級使用者 (root) 的身份執行此公用程式，才擁有建立金鑰庫的權限。)相同的憑證可用於 ssljms、ssladmin 或 cluster 連線服務。

在指令提示符號下輸入以下內容：

imqkeytool -broker

金鑰工具公用程式會提示您輸入金鑰庫密碼。

   Generating keystore for the broker ...
   Enter keystore password:

接著，公用程式會提示您輸入憑證所屬代理程式的識別資訊。您提供的資訊會組成 X.500 辨別名稱。表 7–5 顯示提示以及提供給每個提示的值。這些值不區分大小寫，而且可以包含空格。

輸入完畢後，金鑰工具公用程式會顯示您輸入的資訊，請您確認。例如：

   Is CN=mqserver.sun.com, OU=purchasing, ON=My Company, Inc.,
   L=San Francisco, ST=California, C=US correct?

若要接受目前的值並繼續執行，請輸入 yes；若要重新輸入這些值，請接受預設值或輸入 no。您確認後，此公用程式會產生金鑰對並暫停其他作業。

接著，公用程式會要求您提供用於鎖定金鑰對的密碼 (即金鑰密碼)。看到此提示請按下 Return 鍵，表示金鑰密碼與金鑰庫密碼相同。

請記住您指定的密碼。啟動代理程式時必須提供此密碼，代理程式才能開啟金鑰庫。您可以在密碼檔案中儲存金鑰庫密碼 (請參閱密碼檔案)。

金鑰工具公用程式會產生自我簽署的憑證，並將其放置在 Message Queue 的金鑰庫中。金鑰庫所在目錄取決於作業系統，請參閱附錄 AMessage Queue^TM 資料的特定平台位置。

以下是 SSL 型連線服務之 Message Queue 金鑰庫的可配置特性：

• imq.keystore.file.dirpath：包含金鑰庫檔案之目錄的路徑。如需預設值，請參閱附錄 AMessage Queue^TM 資料的特定平台位置。

• imq.keystore.file.name：金鑰庫檔案的名稱。

• imq.keystore.password：金鑰庫密碼。

有時您可能需要重新產生金鑰對，以解決某些問題：例如，您忘記了金鑰庫密碼，或者啟動代理程式時， SSL 型服務無法初始化，並且您遇到以下異常：

java.security.UnrecoverableKeyException:Cannot recover key

(如果在產生自我簽署的憑證時，所提供的金鑰密碼與金鑰庫密碼不同，則可能導致此異常。)

重新產生金鑰對

1. 移除代理程式的金鑰庫，其位置如附錄 AMessage Queue^TM 資料的特定平台位置中所示。

2. 重新執行 imqkeytool 以產生新的金鑰對，如上所述。

啟用 SSL 型連線服務

若要在代理程式中啟用 SSL 型連線服務，您需要將 ssljms (或 ssladmin) 增加到 imq.service.activelist 特性。

在代理程式中啟用 SSL 型服務

1. 開啟代理程式的實例配置檔案。

   實例配置檔案的所在目錄名稱，與此配置檔案相關聯之代理程式實例名稱 (instanceName) 相同 (請參閱附錄 AMessage Queue^TM 資料的特定平台位置)：

      .../instances/instanceName/props/config.properties
   

2. 增加表示 imq.service.activelist 特性的項目 (如果項目尚未存在)，並將所需的 SSL 型服務納入清單。

   依預設，此特性包括 jms 和 admin 連線服務。增加 SSL 型服務或您要啟動的服務 (ssljms、ssladmin，或兩者)：

   imq.service.activelist=jms,admin,ssljms,ssladmin
   

   ---

   備註 –

   請使用 imq.cluster.transport 特性啟用 SSL 型 cluster 連線服務，而非使用 imq.service.activelist 特性；請參閱連線代理程式。

   ---

3. 儲存並關閉實例配置檔案。

啟動代理程式

啟動代理程式，提供金鑰庫密碼。您可以透過以下任何一種方法提供密碼：

• 允許代理程式在啟動時提示您提供密碼：

     imqbrokerd
     Please enter Keystore password:

• 將密碼放在密碼檔案中，如密碼檔案中所述。然後設定特性 imq.passfile.enabled = true，並執行下列其中一項作業：

  • 將密碼檔案的位置傳送給 imqbrokerd 指令：

    imqbrokerd -passfile /passfileDirectory/passfileName
    

  • 啟動代理程式時，不使用 --passfile 選項，而是透過以下兩個代理程式配置特性來指定密碼檔案的位置：

    imq.passfile.dirpath=/passfileDirectory
    
    imq.passfile.name=passfileName
    

啟動使用 SSL 的代理程式或用戶端時，CPU 使用率可能在幾秒鍾內劇增。這是因為 Message Queue 使用 JSSE (Java Secure Socket Extension) 方法 java.security.SecureRandom 產生隨機數字，此方法建立初始隨機數種子要佔用大量時間。建立種子之後，CPU 使用率會降至正常。

配置並執行 SSL 型用戶端

將用戶端配置為使用 SSL 型連線服務的程序， 根據其為應用程式用戶端 (使用 ssljms 連線服務) 還是 Message Queue 管理用戶端 (例如使用 ssladmin 連線服務的 imqcmd) 而有所不同。

應用程式用戶端

針對應用程式用戶端，您必須確保用戶端在其 CLASSPATH 變數中已指定下列 .jar 檔案：

imq.jar




jms.jar

如果您使用 1.4 版之前的 Java 2 Software Development Kit (J2SDK)，也必須包含下列 Java Secure Socket Extension (JSSE) 和 Java Naming and Directory Interface (JNDI) .jar 檔案：

jsse.jar




jnet.jar




jcert.jar




jndi.jar

(如果您使用 J2SDK 1.4 或更新版本，因為已內建 JSSE 和 JNDI 支援，則不需要包含這些檔案。)

正確指定 CLASSPATH 檔案後，請啟動用戶端並將其連線至代理程式的 ssljms 連線服務，完成此作業的方法之一是輸入以下指令：

java -DimqConnectionType=TLS clientAppName

如此可告知連線使用 SSL 型連線服務。

管理用戶端

針對管理用戶端，您可以透過在呼叫 imqcmd 指令時加入 -secure 選項，來建立安全連線：例如：

imqcmd list svc -b hostName:portNumber -u adminName -secure

其中 adminName 是 Message Queue 使用者儲存庫中的有效項目。此指令會提示您輸入密碼。(如果您使用平面檔案儲存庫，請參閱變更預設管理員密碼)。

列出連線服務是驗證 ssladmin 服務正在執行的一種方法，也可以驗證是否能成功建立安全的管理連線，如下所示：

Listing all the services on the broker specified by:

Host                 Primary Port
localhost            7676

Service Name     Port Number       Service State
admin            33984 (dynamic)   RUNNING
httpjms          -                 UNKNOWN
httpsjms         -                 UNKNOWN
jms              33983 (dynamic)   RUNNING
ssladmin         35988 (dynamic)   RUNNING
ssljms           dynamic           UNKNOWN

Successfully listed services.

使用簽署的憑證

簽署憑證提供的伺服器認證，比自我簽署憑證的伺服器認證更安全。您只能在用戶端和代理程式之間 (不能在叢集的多個代理程式之間) 實作簽署憑證。除了上述配置自我簽署憑證所需步驟之外，您還需要執行下列額外的步驟。後續小節會詳細說明這些步驟。

使用簽署的憑證

1. 在金鑰庫中安裝憑證。

2. 配置 Message Queue 用戶端在建立與代理程式的 SSL 型連線時，請求簽署憑證。

取得並安裝簽署的憑證

下列程序說明如何取得並安裝簽署的憑證。

取得簽署的憑證

1. 使用 J2SE keytool 指令，為您在上節中產生的自我簽署憑證，產生憑證簽署請求 (CSR)。

   下列網站提供有關 keytool 指令的資訊：

   http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/keytool.html

   範例：

   keytool -certreq -keyalg RSA -alias imq -file certreq.csr -keystore /etc/imq/keystore -storepass myStorePassword

   這會產生 CSR，將憑證封裝在指定的檔案中 (此範例中的 certreq.csr )。

2. 使用 CSR 產生或請求簽署的憑證。

   您可以使用下列方法之一：

   • 請 Thawte 或 Verisign 等知名的憑證授權單位 (CA) 簽署憑證。如需如何執行此作業的詳細資訊，請參閱您的 CA 文件。

   • 使用 SSL 簽署套裝軟體，自行簽署憑證。

     簽出的憑證是一串 ASCII 字元。如果您收到 CA 簽署的憑證，它可能是一個電子郵件附件或是郵件中的文字。

3. 將簽署的憑證儲存在檔案中。

   以下說明中，使用 broker.cer 範例名稱來代表代理程式憑證。

安裝簽署的憑證

1. 檢查 J2SE 依預設是否支援您的憑證授權單位。

   以下指令會列出系統金鑰庫中的根 CA：

   keytool -v -list -keystore $JAVA_HOME/lib/security/cacerts
   

   如果有列出您的 CA，請跳過下一個步驟。

2. 如果 J2SE 未支援您的憑證授權單位，請將 CA 的根憑證匯入 Message Queue 金鑰庫中。

   範例：

   keytool -import -alias ca -file ca.cer -noprompt -trustcacerts
           -keystore /etc/imq/keystore -storepass myStorePassword
   

   其中 ca.cer 檔案包含 CA 提供的根憑證。

   如果您使用 CA 測試憑證，可能需要匯入測試 CA 根憑證。您的 CA 應該會指示如何取得該憑證的副本。

3. 將簽署的憑證匯入金鑰庫中，替代原始的自我簽署憑證。

   範例：

   keytool -import -alias imq -file broker.cer -noprompt -trustcacerts
           -keystore /etc/imq/keystore -storepass myStorePassword
   

   broker.cer 是您從 CA 獲得的簽署憑證所在的檔案。

   現在 Message Queue 金鑰庫包含簽署憑證，可用於 SSL 連線。

配置 Message Queue 用戶端執行階段以請求簽署憑證

現在您必須配置 Message Queue 用戶端執行階段以請求簽署的憑證，並確保用戶端信任簽署此憑證的憑證授權單位。

配置用戶端執行階段以請求簽署的憑證

1. 將連線工廠的 imqSSLIsHostTrusted 屬性設定為 false。

   依預設，用戶端將用來建立代理程式連線的連線工廠物件之 imqSSLIsHostTrusted 屬性設定為 true，這表示用戶端執行階段會接受所出示的任何憑證。您必須將此值變更為 false，讓用戶端執行階段嘗試驗證所出示的所有憑證。如果憑證簽署者未出現在用戶端的信任清單存放區，驗證便會失敗。

2. 驗證簽署的授權單位是否已在用戶端的信任清單存放區中註冊。

   若要測試用戶端是否會接受您的憑證授權單位所簽署的憑證，請嘗試建立 SSL 連線，如上節配置並執行 SSL 型用戶端中所述。如果 CA 列在用戶端的信任存放區中，連線便會成功，您可以跳過下一個步驟。如果連線失敗出現憑證驗證錯誤，請執行下一個步驟。

3. 在用戶端的信任存放區中安裝簽署 CA 的根憑證。

   依預設，用戶端會搜尋金鑰庫檔案 cacerts 和 jssecacerts，因此如果憑證安裝在以上其中一個檔案中，便不需要進一步配置。下列範例會將來自 Verisign 憑證授權單位，檔名為 testrootca.cer 的測試根憑證檔案，安裝到預設系統憑證檔案 cacerts 。此範例假設 J2SE 安裝在 $JAVA_HOME/usr/j2se 目錄中：

   keytool -import -keystore /usr/j2se/jre/lib/security/cacerts
           -alias VerisignTestCA -file testrootca.cer -noprompt
           -trustcacerts -storepass myStorePassword
   

   建議使用的替代選項，是將根憑證安裝到替代系統憑證檔案 jssecacerts：

   keytool -import -keystore /usr/j2se/jre/lib/security/jssecacerts
           -alias VerisignTestCA -file testrootca.cer -noprompt
           -trustcacerts -storepass myStorePassword
   

   第三個可能方法是將根憑證安裝到其他金鑰庫檔案中，並且配置用戶端將其視為信任存放區。下列範例會安裝到 /home/smith/.keystore 檔案中：

   keytool -import -keystore /home/smith/.keystore
           -alias VerisignTestCA -file testrootca.cer -noprompt
           -trustcacerts -storepass myStorePassword
   

   由於用戶端依預設不會搜尋此金鑰庫，因此您必須明確向用戶端提供此位置作為信任存放區。若要執行這項操作，請在用戶端執行時，設定 Java 系統特性 javax.net.ssl.trustStore：

   javax.net.ssl.trustStore=/home/smith/.keystore
   

密碼檔案

有些類型的指令需要密碼。表 7–6 中的第一欄列出需要密碼的指令，第二欄列出需要密碼的原因。

您可以在密碼檔案中指定這些密碼，並且使用 -passfile 選項來指定檔案名稱。下面是 -passfile 選項的格式：

imqbrokerd -passfile myPassfile

您可以在舊版的指令行中使用 -p、-password 、-dbpassword 和 -ldappassword 選項來指定密碼。但是這些選項已經被停用，將從未來的版本中移除。在目前的版本中，指令行中這些選項的任一值，會取代密碼檔案中相關的值。

安全考量

除非別人可以看到您的監視器，否則遵照提示以互動式方法指定密碼是最安全的指定密碼方法。您也可以從指令行指定密碼檔案。但若使用非互動式指令，就必須使用密碼檔案。

密碼檔案沒有加密，您必須設定權限以防止無權限者存取此檔案。設定權限來限制哪些使用者檢視檔案，但是允許啟動代理程式的使用者讀取此檔案。

密碼檔案內容

密碼檔案是純文字檔，包含一組特性和值。每一個值是指令使用的密碼。

密碼檔案可以包含表 7–7 中所示密碼：

imq.keystore.password

imq.persist.jdbc.password

imqbrokerd
imdbmgr

imq.user_repository.ldap.password

imqbrokerd

Message Queue 產品提供密碼檔案範例。有關此範例檔案的位置，請參閱附錄 AMessage Queue^TM 資料的特定平台位置。

透過防火牆連線

當用戶端應用程式和代理程式之間被防火牆分隔時，需要採取特殊措施來建立連線。一個方法是使用 httpjms 或 httpsjms 連線服務，在防火牆中「打出通道」；如需詳細資訊，請參閱附錄 CHTTP/HTTPS 支援。不過 HTTP 連線比起其他連線服務較慢；較快速的替代方式是略過 Message Queue 連接埠對映器，並明確指定靜態連接埠位址給所需的連線服務，然後在防火牆開啟此特定的連接埠。這個方法可以使用 jms 或 ssljms 連線服務 (或在不尋常的狀況下，使用 admin 或 ssladmin)，透過防火牆連線。

透過防火牆啟用代理程式連線

1. 將靜態連接埠位址指派給要使用的連線服務。

   若要略過連接埠對映器，並將靜態連接埠號直接指定給連線服務，請設定代理程式配置特性 imq.serviceName. protocolType.port，其中 serviceName 為連線服務名稱，protocolType 為協定類型 (請參閱表 7–8)。如同所有代理程式配置特性，您可以在代理程式的實例配置檔案中指定此特性，或在啟動代理程式時從指令行指定此特性。例如，若要將連接埠號 10234 指派給 jms 連線服務，請在配置檔案中併入下列指令行

      imq.jms.tcp.port=10234
   

   或使用下列指令啟動代理程式

      
   imqbrokerd  -name myBroker  -Dimq.jms.tcp.port=10234
   

2. 配置防火牆以允許連線至指派給連線服務的連接埠號。

   您也必須允許透過防火牆連線至 Message Queue 的連接埠對映器連接埠 (通常是 7676，除非已重新指定連接埠對映器使用其他連接埠)。例如，在以上範例中，您必須針對連接埠 10234 和 7676 開啟防火牆。

稽核記錄

Message Queue 僅在 Enterprise Edition 版本支援稽核記錄。啟用稽核記錄後，Message Queue 會記錄下列類型的事件：

• 啟動、關機、重新啟動及移除代理程式實例

• 使用者認證和授權

• 重設永久性存放區

• 建立、清除及銷毀實體目標

• 管理長期訂閱者銷毀

若要將稽核記錄記入 Message Queue 代理程式記錄檔，請將 imq.audit.enabled 代理程式特性設定為 true。記錄檔中的所有稽核記錄都有關鍵字 AUDIT。

第 8 章 管理受管理物件

受管理物件會封裝提供者專用的配置和命名資訊，這樣能開發可以從 JMS 提供者移植到其他提供者的用戶端應用程式。Message Queue^TM 管理員通常會為用戶端應用程式建立受管理物件，使其能夠與代理程式建立連線，進行傳送與接收訊息。

本章說明如何使用物件管理員公用程式 (imqobjmgr ) 來建立和管理受管理物件。它包含下面各節：

• 物件存放區

• 受管理物件屬性

• 使用物件管理員公用程式

• 新增受管理物件

• 列出受管理物件

• 檢視受管理物件資訊

• 修改受管理物件屬性

物件存放區

受管理物件會置於即時可用的物件存放區中，用戶端應用程式可透過 Java Naming and Directory Interface (JNDI) 存取此處的受管理物件。您可以使用兩種類型的物件存放區︰標準的簡易目錄存取協定 (LDAP) 目錄伺服器，或本機檔案系統中的目錄。

LDAP 伺服器物件存放區

對於生產訊息傳送系統，我們建議使用 LDAP 伺服器作為物件存放區。LDAP 伺服器是專為在分散式系統中使用而設計的，並提供在生產環境中非常有用的安全性功能。

有多家供應商提供 LDAP 實作。若要使用 Message Queue 管理工具來管理 LDAP 伺服器上的物件存放區，首先需要將伺服器配置成可以儲存 Java 物件並執行 JNDI 查找。請參閱 LDAP 實作所隨附的文件，以取得詳細資訊。

使用 LDAP 伺服器作為物件存放區時，您必須指定表 8–1 中所顯示的屬性。這些屬性分為以下幾個種類：

• 初始環境。 java.naming.factory.initial 屬性會指定伺服器上 JNDI 查找的初始環境。各 LDAP 物件存放區有其固定的此屬性值。

• 位置。java.naming.provider.url 屬性會指定 LDAP 伺服器的 URL 和目錄路徑。您必須確認所指定的目錄路徑存在。

• 安全性。java.naming.security.principal、java.naming.security.credentials 和 java.naming.security.authentication 屬性會在呼叫者嘗試存取物件存放區時，管理該呼叫者的認證程序。這些屬性的實際格式和數值視 LDAP 服務提供者而定；請參閱 LDAP 實作所隨附的文件以取得詳細資訊，並判斷所有作業是否均需要有安全性資訊，或者只有變更已儲存資料的作業需要安全性資訊。

檔案系統物件存放區

Message Queue 也支援在本機檔案系統中使用目錄，以作為受管理物件的物件存放區。我們不建議您對生產系統使用此方法，不過此方法具有在開發環境中非常容易使用的優點。但是請注意，如果跨多個電腦節點部署的用戶端將目錄用作集中物件存放區，則這些用戶端都必須擁有該目錄的存取權。除此之外，任何對此目錄擁有存取權的使用者，均可使用 Message Queue 管理工具以建立並管理受管理物件。

使用檔案系統目錄作為物件存放區時，您必須指定表 8–2 中所顯示的屬性。這些屬性大致和上述 LDAP 物件存放區相同，其中特別需要說明的是，java.naming.provider.url 屬性會指定保留物件存放區之目錄的路徑。該目錄必須存在，而且 Message Queue 管理工具的使用者與用戶端應用程式的使用者皆必須擁有適當的存取權限，以供存取存放區。

java.naming.factory.initial

java.naming.provider.url

受管理物件屬性

Message Queue 受管理物件有兩種基本類型：

• 連線工廠：用戶端應用程式可用以建立與代理程式的連線。

• 目標：表示代理程式上用戶端應用程式與其交換 (傳送和接收) 訊息的位置。

特殊 SOAP 端點受管理物件使用於 SOAP 訊息傳送；如需更多資訊，請參閱「Message Queue Developer's Guide for Java Clients」。

每種受管理物件類型均包含決定物件特性及運作方式的屬性。本節描述如何使用物件管理員指令行公用程式 (imqobjmgr) 來設定這些屬性，您也可以使用 GUI 管理主控台進行設定，如使用受管理物件所述。

連線工廠屬性

用戶端應用程式使用連線工廠受管理物件，建立與代理程式交換訊息的連線。連線工廠的屬性會定義由其建立的所有連線之特性。連線一旦建立後，就無法變更其特性，因此配置連線特性的唯一方法，就是設定用以建立連線之連線工廠的屬性。

Message Queue 定義兩種類別的連線工廠物件：

• ConnectionFactory 物件支援一般訊息傳送和非分散式作業事件。

• XAConnectionFactory 物件支援分散式作業事件。

這兩種類別共用相同的配置屬性，您可以使用這些屬性最佳化資源、效能和訊息流量。第 16 章, 受管理物件屬性參照中列出這些屬性並有詳細說明，下列各節將討論這些屬性：

• 連線處理

• 用戶端標識

• 可靠性與流量控制

• 佇列瀏覽器和伺服器階段作業

• 標準訊息特性

• 訊息標頭置換

連線處理

連線處理屬性會指定要連線至哪個代理程式位址，並會視需要指定偵測連線失敗和嘗試重新連線的方式。在表 16–1 有這些屬性的摘要說明。

代理程式位址清單

最重要的連線處理屬性是 imqAddressList ，該屬性會指定要與其建立連線的代理程式。此屬性值是一個字串，其中包含一個代理程式位址或 (如果是代理程式叢集) 由逗號分隔的多個位址。視所使用的連線服務 (請參閱連線服務) 和建立連線的方法之不同，代理程式位址可使用多種定址方案：

• mq 使用代理程式的連接埠對映器，為 jms 或 ssljms 連線服務動態地指定連接埠。

• mqtcp 會略過連接埠對映器，並使用 jms 連線服務，直接連線至指定的連接埠。

• mqssl 使用 ssljms 連線服務，為指定的連接埠建立安全通訊端層 (SSL) 連線。

• http 使用 httpjms 連線服務，將超文字傳輸協定 (HTTP) 連線至指定 URL 的 Message Queue 通道 Servlet。

• https 使用 httpsjms 連線服務，將安全超文字傳輸協定 (HTTPS) 連線至指定 URL 的 Message Queue 通道 Servlet。

這些定址方案在表 16–2 中有所摘要。

每個代理程式位址的一般格式為

scheme://address

其中 scheme 是上述所列的其中一個定址方案，而 address 則表示代理程式位址本身。指定位址的確切語法會因定址機制而異，如表 16–2 中的最後一欄所示。表 16–3 顯示不同位址格式範例。

在有多個代理程式的叢集環境中，位址清單可包含多個代理程式位址。如果第一個連線嘗試失敗，Message Queue 用戶端執行階段會嘗試連線至清單中的另一個位址，以此類推，一直到清單上所有位址都試完為止。有兩個額外的連線工廠屬性會控制完成此作業的方式：

• imqAddressListBehavior 會指定特定位址的嘗試順序。如果此屬性設定為 PRIORITY 字串，將會以在位址清單中出現的順序來嘗試連線位址。如果屬性值是 RANDOM，則會以隨機的順序來嘗試連線位址；例如，當有許多 Message Queue 用戶端共用相同的連線工廠物件時，這會有效避免用戶端全部嘗試連線至相同的代理程式位址。

• imqAddressListIterations 會指定在放棄並報告失敗之前，循環清單的次數。數值 -1 表示不限制循環次數：用戶端執行階段會繼續嘗試，直到成功建立連線或時間終了為止 (視哪種情況先發生)。

自動重新連線

您可以將連線工廠的 imqReconnectEnabled 屬性設定為 true，讓用戶端在連線失敗時，能自動重新連線至代理程式。imqReconnectAttempts 屬性會控制重新連線至指定代理程式位址的嘗試次數；imqReconnectInterval 會指定兩次連線嘗試之間的等待時間間隔 (以毫秒為單位)。

代理程式位址清單 (imqAddressList ) 在代理程式叢集中會指定多個位址，失敗的連線不只會在原始代理程式上復原，也會在叢集中其他代理程式上復原。如果重新連線至原始代理程式失敗，則用戶端執行階段將會嘗試清單中的其他位址。如上節所述，imqAddressListBehavior 和 imqAddressListIterations 屬性會控制嘗試連線位址的順序，以及清單循環的次數。每個位址會以 imqReconnectInterval 毫秒的時間間隔重複嘗試，嘗試次數上限由 imqReconnectAttempts 指定。

自動重新連線支援訊息使用的所有用戶端確認模式。連線一旦重新建立，代理程式就會重新傳送之前已傳送但尚未確認的所有訊息，並使用 Redeliver 旗標加以標記。應用程式碼可使用此旗標來判斷是否有已使用但尚未確認的訊息。(但是，如果不是長期訂閱者，一旦關閉連線，代理程式將不會保留訊息。因此當連線關閉時，為這類訂閱者所產生的任何訊息將無法在重新連線後傳送，而會遺失。) 進行自動重新連線時會阻斷訊息的產生，因此訊息產生器在連線尚未重新建立之前，無法傳送訊息到代理程式。

自動重新連線可提供連線容錯移轉功能，但不提供資料容錯移轉功能：當用戶端重新連線至不同的代理程式實例時，失敗或連線中斷的代理程式所保留的永久性訊息和其他狀態資訊將會遺失。嘗試重新建立連線時，Message Queue 會維護用戶端執行階段所提供的物件 (例如階段作業、訊息用戶和訊息產生器)。當連線失敗時，也會保留暫時目標一段時間，因為用戶端可能會重新連線並再次存取這些目標；在用戶端利用這段時間重新連線並使用這些目標之後，代理程式就會刪除這些目標。如果重新連線後，無法在代理程式上完全復原用戶端狀態 (例如，當使用只有在連線期間才存在的已處理之階段作業時)，將不會進行自動重新連線，而是會呼叫連線的異常處理程式。接著會由應用程式碼擷取異常、重新連線及復原狀態。

定期測試 (Ping) 連線

Message Queue 用戶端執行階段可以配置成定期測試或「Ping」連線，在嘗試的訊息傳輸失敗前，就事先偵測到連線失敗。如果用戶端應用程式只是使用訊息而並不產生這些訊息，則此項測試特別重要，因為這類應用程式無法以其他方式偵測到連線失敗。很少產生訊息的用戶端也可受惠於此功能。

連線工廠屬性 imqPingInterval 會指定使用 Ping 指令偵測連線的頻率 (以秒為單位)。依預設，時間間隔設定為 30 秒，數值 -1 表示停用 Ping 作業。

Ping 失敗的回應會根據不同的作業系統平台而有所差異。在某些系統上，會立即對用戶端應用程式的異常偵聽程式丟出一個異常。(如果用戶端沒有異常偵聽程式，則該用戶端下次嘗試使用連線時將會失敗。)其他的系統可能會繼續嘗試建立與代理程式的連線，緩衝連續的偵測，直到偵測成功或緩衝區溢位為止。

用戶端標識

表 16–4 中所列的連線工廠屬性，支援用戶端認證以及長期訂閱者的用戶端識別碼設定。

用戶端認證

連線至代理程式的所有嘗試，必須透過將使用者名稱和密碼與訊息服務維護的使用者儲存庫進行對照的方式認證。如果用戶端在建立連線時，未明確提供使用者名稱和密碼，則使用由連線工廠屬性 imqDefaultUsername 和 imqDefaultPassword 指定的預設使用者名稱和密碼。

Message Queue 提供 guest 使用者帳號 (其中使用者名稱和密碼均為 guest)，以省去開發者在應用程式開發和測試期間需要寫入使用者儲存庫的麻煩。這也是 imqDefaultUsername 和 imqDefaultPassword 屬性的預設值，因此如果這些屬性沒有明確指定，用戶端一律可以使用 guest 帳號取得連線。在生產環境中，對代理程式連線的存取應僅限於在使用者儲存庫中明確註冊的使用者。

用戶端識別碼

每當代理程式必須為用戶端維護持續性狀態時，Java 訊息服務規格會要求連線提供唯一的用戶端識別碼。Message Queue 使用這類用戶端識別碼，追蹤主題目標的長期訂閱者。如果長期訂閱者變為非使用中的狀態，則代理程式會保留該主題的所有內送訊息，等到此訂閱者回復為使用中狀態時，再傳送這些訊息。代理程式會藉由用戶端識別碼來識別用戶。

用戶端應用程式可能會使用連線物件的 setClientID 方法，透過程式設計來設定自己的用戶端識別碼，因此很難協調用戶端識別碼並確保每個識別碼都是唯一的。通常比較好的方式是讓 Message Queue 在為用戶端建立連線時，自動指定唯一的識別碼。若要這麼做，請將連線工廠的 imqConfiguredClientID 屬性設定為下列格式的值

${u}factoryID

${u} 字元必須為屬性值的前四個字元。(在括弧之間若有 u 以外的其他字元，會造成在建立連線時丟出一個異常；如果是在其他位置，則這些字元並不具有任何特殊意義，而會被當作是純文字來處理。)factoryID 的值是唯一與此連線工廠物件關聯的字元字串。

為特定用戶端建立連線時，Message Queue 會以 u:userName 取代 ${u} 字元，以建構用戶端識別碼，其中 userName 是供連線認證的使用者名稱。這可確保指定連線工廠所建立的每個連線即便在其他方面都相同，也會有唯一的用戶端識別碼。例如，如果使用者名稱是 Calvin，而為連線工廠的 imqConfiguredClientID 屬性指定的字串是 ${u}Hobbes，則指定的用戶端識別碼會是 u:CalvinHobbes。

如果有兩個用戶端都使用預設的使用者名稱 guest 以嘗試取得連線，則無法使用此方案，因為對於這兩個用戶端的用戶端識別碼，其 ${u} 部分會完全相同。在這種情況下，只有第一個請求連線的用戶端才能取得連線，第二個嘗試連線的用戶端則會失敗，因為 Message Queue 無法使用同一用戶端識別碼建立兩個連線。

即使您使用 imqConfiguredClientID 指定用戶端識別碼，用戶端應用程式還是會使用連線方法 setClientID 置換此設定值。您可以將連線工廠的 imqDisableSetClientID 屬性設定為 true，以避免這種情況。請注意，對於使用長期訂閱者的應用程式，其用戶端識別碼必須以下列兩種方法之一進行設定：使用 imqConfiguredClientID 以管理員方式設定，或者使用 setClientID 以程式設計方式設定。

可靠性與流量控制

由於用戶端傳送與接收的「有效負載」訊息以及 Message Queue 本身使用的控制訊息 (例如代理程式確認) 透過相同的用戶端與代理程式連線傳送，因此過量的有效負載流量可能會干擾控制訊息的傳送。若要協助減輕此問題，表 16–5 中所列的連線工廠屬性可讓您管理這兩類訊息的相對流量。這些屬性可分為四種：

• 確認逾時：指定在丟出異常之前，等待代理程式確認的最長時間 (imqAckTimeout)。

• 連線流量計數：會限制將有效負載訊息以指定的大小分批次進行傳輸 (imqConnectionFlowCount)，以確保可定期傳送任何累積的控制訊息。

• 連線流量控制：會限制連線上可以保留之擱置的有效負載訊息數 (imqConnectionFlowLimit)。達到限制時，傳送到連線的有效負載訊息會暫停，直到等待使用的訊息數量降到限制以下為止。此功能的使用是由布林值旗標 (imqConnectionFlowLimitEnabled) 所控制。

• 用戶流量控制：會限制任何單一用戶可以擱置等待使用的有效負載訊息數 (imqConsumerFlowLimit)。(此限制也可以指定為特定佇列目標的特性 consumerFlowLimit。)達到限制時，會暫停傳送有效負載訊息至用戶，直到等待使用的訊息數量 (imqConsumerFlowLimit 以百分比表示) 降到 imqConsumerFlowThreshold 屬性所指定的限制以下為止。這可以防止任何用戶佔用連線讓別人苦等，幫助改善多名用戶之間的負載平衡。

使用這些流量控制技術必須在可靠性與流量之間進行權衡；如需詳細說明，請參閱用戶端執行階段訊息流量調校。

佇列瀏覽器和伺服器階段作業

表 16–6 會列出影響用戶端佇列瀏覽與伺服器階段作業的連線工廠屬性。imqQueueBrowserMaxMessagesPerRetrieve 屬性會指定瀏覽佇列目標內容時，一次擷取的最大訊息數；imqQueueBrowserRetrieveTimeout 會指定擷取訊息的最長等待時間。(請注意，imqQueueBrowserMaxMessagesPerRetrieve 不會影響所瀏覽的訊息總數，而只是影響將訊息分為資料塊以便傳送至用戶端執行階段的方式：分為數目少但內容多的資料塊，或是分為數目多但內容少的資料塊。用戶端應用程式一定會收到佇列中的所有訊息。變更屬性值可能會影響效能，但不會影響所擷取的資料總數。) 布林值屬性 imqLoadMaxToServerSession 控制連線用戶在應用程式伺服器階段作業中的運作方式：若此屬性值為 true，用戶端就會將最大數量的訊息載入到伺服器階段作業中；若為 false，則用戶端一次僅載入一則訊息。

標準訊息特性

Java Message Service 規格會定義部分標準訊息特性，JMS 提供者 (例如 Message Queue) 可以選擇性支援這些特性。根據慣例，所有這類標準特性的名稱會以字母 JMSX 開頭。表 16–7 中所列的連線工廠屬性，可控制用戶端執行階段是否設定這類標準特性中的部分特性。對於產生的訊息，包括下列特性：

• JMSXUserID 傳送訊息之使用者的身份識別

• JMSXAppID 傳送訊息之應用程式的身份識別

• JMSXProducerTXID 產生訊息之作業事件的作業事件識別碼

對於使用的訊息，則包括

• JMSXConsumerTXID 使用訊息之作業事件的作業事件識別碼

• JMSXRcvTimestamp 訊息傳送至用戶的時間

訊息標頭置換

您可以使用表 16–8 中所列的連線工廠屬性，置換用戶端為特定 JMS 訊息標頭欄位所設定的值。由該連線工廠取得的連線所產生之所有訊息會使用您指定的設定值。您可以此方式置換的標頭欄位包括：

• JMSDeliveryMode 傳送模式 (永久性或非永久性)

• JMSExpiration 過期時間

• JMSPriority 優先權層級

如上所述的每個欄位均有兩個屬性：一個是控制能否置換該欄位的布林值，另一個屬性則指定該欄位的值。例如，設定優先權層級的屬性是 imqOverrideJMSPriority 和 imqJMSPriority。另外還有一個屬性 imqOverrideJMSHeadersToTemporaryDestinations，用來控制置換值是否會套用到暫時目標。

由於置換訊息標頭可能會干擾特定應用程式的需求，因此請先諮詢應用程式設計者或使用者，然後再使用這些屬性。

目標屬性

識別實體佇列或主題目標的目標受管理物件只有兩個屬性，如表 16–7 中所列。其中的 imqDestinationName 屬性較為重要，該屬性提供此受管理物件所代表的實體目標名稱；這個名稱是在使用 imqcmd create dst 指令建立實體目標時透過 -n 選項所指定。(請注意，目標受管理物件和其代表的實體目標之間不一定存有一對一的關係：單一實體目標可以被多個受管理物件所參照，或不被任何受管理物件所參照。) 另外還有一個選擇性描述字串 imqDestinationDescription，可用以協助您識別目標物件，讓其與您之前建立的物件有所區分。

使用物件管理員公用程式

Message Queue 物件管理員公用程式 (imqobjmgr) 可讓您建立並管理受管理物件。imqobjmgr 指令提供下列子指令，以便在受管理物件上執行各種作業：

add

將受管理物件增加至物件存放區

delete

從物件存放區刪除受管理物件

list

列出物件存放區中現有的受管理物件

query

顯示有關受管理物件的資訊

update

修改受管理物件的屬性

如需 imqobjmgr 指令的語法、子指令和選項之參考資訊，請參閱物件管理員公用程式。

大多數物件管理員作業需要您指定下列資訊以作為 imqobjmgr 指令的選項：

• 受管理物件的 JNDI 查找名稱 (-l)

  用戶端應用程式會依據這個邏輯名稱，使用 Java Naming and Directory Interface 在物件存放區中查找受管理物件。

• JNDI 物件存放區的屬性 (-j)

  如需有關可能的屬性及其值的資訊，請參閱物件存放區。

• 受管理物件的類型 (-t)

  可能的類型包括：

  q

  佇列目標

  t

  主題目標

  cf

  連線工廠

  qf

  佇列連線工廠

  tf

  主題連線工廠

  xcf

  分散式作業事件的連線工廠

  xqf

  分散式作業事件的佇列連線工廠

  xtf

  分散式作業事件的主題連線工廠

  e

  SOAP 端點

• 受管理物件的屬性 (-o)

  如需有關可能的屬性及其值的資訊，請參閱受管理物件屬性。

新增受管理物件

imqobjmgr 指令的 add 子指令，會將連線工廠和主題或佇列目標的受管理物件增加至物件存放區。儲存在 LDAP 物件存放區中的受管理物件必須擁有以 cn= 字首開頭的查找名稱；檔案系統物件存放區中的查找名稱則不需要有特定的字首，但是絕對不能包含斜線字元 (/)。

物件管理員僅會列出與顯示 Message Queue 受管理物件。如果物件存放區中包含非 Message Queue 物件，而且其查找名稱與您想增加的受管理物件名稱相同，則當您嘗試執行增加作業時會出現錯誤。

新增連線工廠

若要讓用戶端應用程式能建立代理程式連線，請為要建立的連線類型增加連線工廠受管理物件：佇列連線工廠或主題連線工廠。範例 8–1 中顯示的指令，會將佇列連線工廠 (受管理物件類型 qf) 增加至 LDAP 物件存放區。物件具有查找名稱 cn=myQCF，並使用 jms 連線服務連線至連接埠號 7272 之主機 myHost 上所執行的代理程式。

範例 8–1 新增連線工廠

imqobjmgr add
   -l "cn=myQCF"
   -j "java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory"
   -j "java.naming.provider.url=ldap://mydomain.com:389/o=imq"
   -j "java.naming.security.principal=uid=homerSimpson,ou=People,o=imq"
   -j "java.naming.security.credentials=doh"
   -j "java.naming.security.authentication=simple"
   -t qf
   -o "imqAddressList=mq://myHost:7272/jms"

新增目標

建立代表目標的受管理物件時，最好先建立實體目標，再將受管理物件增加至物件存放區中。使用指令公用程式 (imqcmd ) 建立實體目標，如建立實體目標中所述。

範例 8–2 中顯示的指令，會將受管理物件增加至代表主題目標之 LDAP 物件存放區，且該目標的查找名稱為 myTopic，實體目標名稱為 physTopic。增加佇列目標的指令很類似，不同之處在於受管理物件類型 (-t 選項) 為 q (表示「佇列目標」)，而非 t (表示「主題目標」)。

範例 8–2 將目標新增至 LDAP 物件存放區

imqobjmgr add
   -l "cn=myTopic"
   -j "java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory"
   -j "java.naming.provider.url=ldap://mydomain.com:389/o=imq"
   -j "java.naming.security.principal=uid=homerSimpson,ou=People,o=imq"
   -j "java.naming.security.credentials=doh"
   -j "java.naming.security.authentication=simple"
   -t t
   -o "imqDestinationName=physTopic"

範例 8–3 中顯示相同的指令，但是受管理物件存放區在 Solaris 檔案系統中，而不是在 LDAP 伺服器中。

範例 8–3 將目標新增至檔案系統物件存放區

imqobjmgr add
   -l "cn=myTopic"
   -j "java.naming.factory.initial=
           com.sun.jndi.fscontext.RefFSContextFactory"
   -j "java.naming.provider.url=file:///home/foo/imq_admin_objects"
   -t t
   -o "imqDestinationName=physTopic"

刪除受管理物件

若要從物件存放區刪除受管理物件，請使用 imqobjmgr 指令的 delete 子指令，指定要刪除的物件之查找名稱、類型和位置。範例 8–4 中顯示的指令會刪除上述新增目標中增加的物件。

範例 8–4 刪除受管理物件

imqobjmgr delete
   -l "cn=myTopic"
   -j "java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory"
   -j "java.naming.provider.url=ldap://mydomain.com:389/o=imq"
   -j "java.naming.security.principal=uid=homerSimpson,ou=People,o=imq"
   -j "java.naming.security.credentials=doh"
   -j "java.naming.security.authentication=simple"
   -t t

列出受管理物件

您可以使用物件管理員的 list 子指令，列出物件存放區中的所有受管理物件，或列出特定類型的受管理物件。範例 8–5 顯示如何列出 LDAP 伺服器上所有的受管理物件。

範例 8–5 列出所有受管理物件

imqobjmgr list
   -j "java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory"
   -j "java.naming.provider.url=ldap://mydomain.com:389/o=imq"
   -j "java.naming.security.principal=uid=homerSimpson,ou=People,o=imq"
   -j "java.naming.security.credentials=doh"
   -j "java.naming.security.authentication=simple"

範例 8–6 列出所有佇列目標 (類型 q)。

範例 8–6 列出特定類型的受管理物件

imqobjmgr list
   -j "java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory"
   -j "java.naming.provider.url=ldap://mydomain.com:389/o=imq"
   -j "java.naming.security.principal=uid=homerSimpson,ou=People,o=imq"
   -j "java.naming.security.credentials=doh"
   -j "java.naming.security.authentication=simple"
   -t q

檢視受管理物件資訊

query 子指令會顯示特定受管理物件的相關資訊，識別該物件的方法，是利用其查找名稱和包含該物件的物件存放區屬性。範例 8–7 顯示查找名稱為 cn=myTopic 之物件的相關資訊。

範例 8–7 檢視受管理物件資訊

imqobjmgr query
   -l "cn=myTopic"
   -j "java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory"
   -j "java.naming.provider.url=ldap://mydomain.com:389/o=imq"
   -j "java.naming.security.principal=uid=homerSimpson,ou=People,o=imq"
   -j "java.naming.security.credentials=doh"
   -j "java.naming.security.authentication=simple"

修改受管理物件屬性

若要修改受管理物件的屬性，請使用 imqobjmgr update 子指令。請提供物件的查找名稱和位置，再使用 -o 選項指定新的屬性值。

修改受管理物件屬性針對範例 8–8 中增加至物件存放區的佇列連線工廠，變更其 imqReconnectAttempts 屬性值。

範例 8–8 修改受管理物件的屬性

imqobjmgr update
   -l "cn=myQCF"
   -j "java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory"
   -j "java.naming.provider.url=ldap://mydomain.com:389/o=imq"
   -j "java.naming.security.principal=uid=homerSimpson,ou=People,o=imq"
   -j "java.naming.security.credentials=doh"
   -j "java.naming.security.authentication=simple"
   -t qf
   -o "imqReconnectAttempts=3"

使用指令檔

imqobjmgr 指令的 -i 選項，可讓您指定使用 Java 特性檔案語法的指令檔名稱，以表示所有或部分子指令陳述式。此功能在指定物件存放區屬性時極為有用，執行這類作業時一般需要大量的鍵入操作，並且在多次呼叫 imqobjmgr 時所鍵入的內容可能都相同。使用指令檔也可讓您避免超出指令行所允許的最大字元數。

範例 8–9 顯示物件管理員指令檔的一般語法。請注意，version 屬性不是指令行選項：這表示指令檔本身的版本 (而不是 Message Queue 產品的版本)，且必須將值設定為 2.0。

範例 8–9 物件管理員指令檔語法

version=2.0
cmdtype=[ add | delete | list | query | update ]
obj.lookupName=lookup name
objstore.attrs.objStoreAttrName1=value1
objstore.attrs.objStoreAttrName2=value2
   . . .
objstore.attrs.objStoreAttrNameN=valueN
obj.type=[ q | t | cf | qf | tf | xcf | xqf | xtf | e ]
obj.attrs.objAttrName1=value1
obj.attrs.objAttrName2=value2
   . . .
obj.attrs.objAttrNameN=valueN

例如，之前在範例 8–1 中所顯示的物件管理員指令，會將佇列連線工廠增加至 LDAP 物件存放區。此指令可以封裝在範例 8–10 中所示的指令檔中。若是指令檔命名為 MyCmdFile，您可以使用指令行執行指令

imqobjmgr -i MyCmdFile

範例 8–10 指令檔範例

version=2.0
cmdtype=add
obj.lookupName=cn=myQCF
objstore.attrs.java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory
objstore.attrs.java.naming.provider.url=ldap://mydomain.com:389/o=imq
objstore.attrs.java.naming.security.principal=\\
                                       uid=homerSimpson,ou=People,o=imq
objstore.attrs.java.naming.security.credentials=doh
objstore.attrs.java.naming.security.authentication=simple
obj.type=qf
obj.attrs.imqAddressList=mq://myHost:7272/jms

指令檔也可以用來僅指定 imqobjmgr 子指令陳述式的一部分，剩下部分則由指令行明確提供。例如，範例 8–11 中所示的指令檔僅指定了 LDAP 物件存放區的屬性值。

範例 8–11 部分指令檔

version=2.0
objstore.attrs.java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory
objstore.attrs.java.naming.provider.url=ldap://mydomain.com:389/o=imq
objstore.attrs.java.naming.security.principal=\\
                                       uid=homerSimpson,ou=People,o=imq
objstore.attrs.java.naming.security.credentials=doh
objstore.attrs.java.naming.security.authentication=simple

您可以接著使用此指令檔，以 imqobjmgr 指令來指定物件存放區，同時明確提供其餘選項，如範例 8–12 所示。

範例 8–12 使用部分指令檔

imqobjmgr add
   -l "cn=myQCF"
   -i MyCmdFile
   -t qf
   -o "imqAddressList=mq://myHost:7272/jms"

視您所使用的平台而定，可於以下位置找到指令檔的其他範例︰

Solaris：/usr/demo/imq/imqobjmgr Linux：/opt/sun/mq/examples/imqobjmgr Windows：IMQ_HOME/demo/imqobjmgr

第 9 章 使用代理程式叢集

Message Queue^TM Enterprise Edition 支援使用代理程式叢集，也就是會共同協作，向用戶端提供訊息傳送服務的代理程式群組。叢集可使訊息服務透過分發用戶端的連線至數個代理程式，來延展其訊息流量的作業。如需叢集和其運作方式的一般說明，請參閱「Message Queue 技術摘要」。

本章描述如何管理代理程式叢集、將叢集與代理程式連線並進行配置。它包含下面各節：

• 叢集配置特性

• 管理叢集

• 主代理程式

叢集配置特性

您可以為叢集的每個代理程式成員指定叢集配置特性，以定義叢集。您可以為叢集中的每個代理程式個別設定這些特性，但通常較方便的做法是將所有配置特性集中至所有代理程式均參照的叢集配置檔案中。這樣可以防止違反合約的設定，並確保叢集中的所有代理程式都能共用相同且一致的配置資訊。

叢集配置特性詳述於表 14–9 中。這些部分包括：

• imq.cluster.brokerlist 將主機名稱和連接埠號賦予屬於叢集的所有代理程式。

• imq.cluster.masterbroker 指定哪一個代理程式 (若有) 為記錄狀態變更的主代理程式。

• imq.cluster.url 指定叢集配置檔案 (若有) 的位置。

• imq.cluster.hostname 將主機名稱或 IP 位址賦予 cluster 連線服務，用於在叢集的各代理程式之間進行內部通訊。如果有多個主機，此設定才會有用：例如，如果一部電腦中有多個網路介面卡。

• imq.cluster.port 將連接埠號賦予 cluster 連線服務。

• imq.cluster.transport 指定 cluster 連線服務所使用的傳輸協定，例如 tcp 或 ssl。

您可以單獨設定個別代理程式的 hostname 和 port 特性，但是叢集中所有代理程式的 brokerlist、masterbroker、url 和 transport 值必須相同。

以下各節描述如何設定代理程式叢集配置特性，可以為叢集中的每個代理程式個別設定，或者使用叢集配置檔案集中設定。

設定個別代理程式的叢集特性

您可以在代理程式的實例配置檔案中 (或啟動代理程式時在指令行上) 設定叢集配置特性。例如，若要建立的叢集包含 host1 連接埠 9876 上、host2 連接埠 5000 上和 ctrlhost 預設連接埠 (7676) 上的代理程式，三個代理程式的實例配置檔案中都將包含以下的特性：

imq.cluster.brokerlist=host1:9876,host2:5000,ctrlhost

請注意，如果您需要變更叢集配置，則此方法要求更新叢集中所有代理程式的實例配置檔案。

使用叢集配置檔案

基於一致性以及便於維護的考量，建議您將所有的共用叢集配置特性集合至單一叢集配置檔案中，而不要為每個代理程式個別地進行設定。在此方法中，每個代理程式的實例配置檔案都必須設定 imq.cluster.url 特性指向叢集配置檔案的位置，例如：

imq.cluster.url=file:/home/cluster.properties

接著，叢集配置檔案會為叢集中的所有代理程式定義共用配置特性，例如要連線的代理程式清單 (imq.cluster.brokerlist)、用於 cluster 連線服務的傳輸協定 (imq.cluster.transport )，以及可以選擇性設定的主代理程式的位址 (imq.cluster.masterbroker)。以下的程式碼定義與上一個範例中相同的叢集，其中在 ctrlhost 上執行的代理程式作為主代理程式：

imq.cluster.brokerlist=host1:9876,host2:5000,ctrlhost
imq.cluster.masterbroker=ctrlhost

管理叢集

本節說明如何連線一組代理程式以形成一個叢集、將新的代理程式增加至現有叢集，以及從叢集中移除代理程式。

連線代理程式

有兩種通用方法可將代理程式連線至叢集：從指令行使用 -cluster 選項進行連線，或在 叢集配置檔案中設定 imq.cluster.brokerlist 特性。無論使用哪種方法，您啟動的每個代理程式每 5 秒鐘會嘗試連線至其他代理程式；在此叢集中的主代理程式 (如果已配置) 啟動後，連線即可成功。如果叢集中有代理程式比主代理程式先啟動，則此代理程式將保持暫停狀態，從而拒絕用戶端連線，直到主代理程式啟動時；然後暫停的代理程式的全部功能將自動可用。

若要從指令行配置代理程式叢集，請在啟動每個代理程式時，使用 imqbrokerd 指令的 -cluster 選項，指定叢集的完整代理程式清單。例如，以下指令啟動新的代理程式，並將其連線至在 host1 的預設連接埠 (7676) 上執行的代理程式、在 host2 的連接埠 5000 上執行的代理程式，以及在預設主機 (localhost) 的連接埠 9876 上執行的代理程式：

imqbrokerd -cluster host1,host2:5000,:9876

另一種更適合用於生產系統的替代方法，就是建立一個使用 imq.cluster.brokerlist 特性的叢集配置檔案，以指定要連線之代理程式的清單。叢集中的每個代理程式均必須將自己的 imq.cluster.url 特性設定為指向此叢集配置檔案。

無論您使用哪種方法，都必須確定叢集中沒有代理程式位址解譯為網路迴路 IP 位址 (127.0.0.1)。任何配置為這個位址的代理程式將無法連線至叢集中的其他代理程式。

一些 Linux 安裝程式會自動將 localhost 項目設定為網路迴路位址。在這類系統上，您必須修改系統 IP 位址，這樣才能為叢集中的所有代理程式設定正確的位址。

在設定叢集時，請在參與叢集的所有 Linux 系統中檢查 /etc/hosts 檔案。如果系統使用的是靜態 IP 位址，請編輯 /etc/hosts 檔案，為 localhost 指定正確的位址。如果位址已註冊網域命名服務 (DNS)，請編輯 /etc/nsswitch.conf 檔案以變更項目的順序，讓系統可以在參考本機 hosts 檔案之前執行 DNS 查找。/etc/nsswitch.conf 中的行應如下所示：

hosts:dns files

如果您想要在叢集中的代理程式之間以安全加密的方式進行訊息傳送，請配置 cluster 連線服務以使用 SSL 型傳輸協定。針對叢集中的每個代理程式，設定 SSL 型連線服務，如訊息加密中所述。然後再使用叢集配置檔案，或透過為每個代理程式個別設定的方式，將 imq.cluster.transport 特性設定為 ssl。

將代理程式新增至叢集

將新代理程式增加至叢集的程序取決於叢集是否使用叢集配置檔案。

使用叢集配置檔案將新的代理程式新增至叢集

1. 將新代理程式增加至叢集配置檔案中的 imq.cluster.brokerlist 特性。

2. 向叢集中的每個代理程式發出以下指令：

   imqcmd reload cls

   此指令強制所有代理程式重新載入叢集配置，確保此叢集中代理程式的所有永久性資訊均為最新的。請注意，您不需要為叢集中的每個代理程式發出此指令；只要對任何一個代理程式執行此指令，就會使得所有代理程式都重新載入叢集配置。

3. (選擇性) 在代理程式的 config.properties 檔案中設定 imq.cluster.url 特性的值，讓其指向叢集配置檔案。

4. 啟動新的代理程式。

   如果您並未執行將代理程式新增至叢集，請使用 imqbrokerd 指令行上的 -D 選項以設定 imq.cluster.url 的值。

不使用叢集配置檔案將新的代理程式新增至叢集

您可以編輯 config.properties 檔案或使用 imqbrokerd 指令行上的 -D 選項來設定以下特性的值：

• imq.cluster.brokerlist

• imq.cluster.masterbroker (如有需要)

• imq.cluster.transport (如果您是使用安全 cluster 連線服務)

從叢集中移除代理程式

您用來從叢集中移除代理程式的方法，取決於原先是透過指令行建立叢集，還是使用集中叢集配置檔案所建立。

使用指令行移除代理程式

如果您是使用指令行的 imqbrokerd 指令將代理程式連線至叢集，則必須停止各代理程式，然後在指令行上指定一組新的叢集成員並重新啟動。程序如下：

使用指令行從叢集中移除代理程式

1. 使用 imqcmd 指令停止叢集中的各代理程式。

2. 重新啟動將保留在叢集中的代理程式 (使用 imqbrokerd 指令的 -cluster 選項，指定要保留的代理程式)。

   例如，假設您原本使用以下的指令來啟動 A、B 和 C 代理程式來建立包含這三者的叢集：

   imqbrokerd -cluster A,B, C

   若要從叢集中移除代理程式 A，請使用以下指令重新啟動代理程式 B 和 C：

   imqbrokerd -cluster B,C

使用叢集配置檔案移除代理程式

如果您原本是集中使用叢集配置檔案中的 imq.cluster.brokerlist 特性來指定叢集的成員代理程式以建立叢集，就不需要為了移除其中一個代理程式而停止所有的代理程式。反之，您只要編輯配置檔案來排除要移除的代理程式，以強制剩餘的叢集成員重新載入叢集配置，並重新配置已排除的代理程式，這樣它就不再指向相同的叢集配置檔案。程序如下：

使用叢集配置檔案從叢集中移除代理程式

1. 編輯叢集配置檔案，從以 imq.cluster.brokerlist 特性指定的清單中移除要排除的代理程式。

2. 向叢集中每個保留的代理程式發出以下指令：

   imqcmd reload cls

   這會強制代理程式重新載入叢集配置。

3. 停止要從叢集中移除的代理程式。

4. 編輯此代理程式的 config.properties 檔案，移除 imq.cluster.url 特性或指定一個不同的值。

主代理程式

您可以選擇是否讓叢集擁有一個主代理程式，它可維護配置變更記錄，以記錄叢集持續性狀態中的任何變更。無論在叢集配置檔案或個別代理程式的實例配置檔案中，主代理程式都是由 imq.cluster.masterbroker 配置特性所識別。

配置變更記錄包含與叢集相關聯之永久性實體中的變更資訊，例如長期訂閱和管理員建立之實體目標。叢集中的所有代理程式會在啟動期間參考主代理程式，以更新這些永久性實體的資訊。主代理程式發生故障時，將無法進行這類同步化作業；如需更多資訊，請參閱當主代理程式無法使用時。

管理配置變更記錄

由於配置變更記錄包含重要資訊，您必須定期進行備份，使其能夠在發生故障的情況下復原。雖然從備份中復原將會失去自當時備份後叢集持續性狀態中的任何變更，但經常定期備份可儘量減低此潛在的資訊遺失。備份與復原作業可以有效地壓縮和最佳化包含在配置變更記錄中的變更歷史，且配置變更記錄能夠隨著時間而迅速增長。

備份配置變更記錄

使用 imqbrokerd 指令的 -backup 選項來指定備份檔案的名稱。例如：

imqbrokerd -backup mybackuplog

復原配置變更記錄

1. 關閉叢集中的所有代理程式。

2. 使用下列指令從備份檔案中復原主代理程式的配置變更記錄

   imqbrokerd -restore mybackuplog

3. 如果您為主代理程式指定一個新的名稱或連接埠號，請相應地在叢集配置檔案中更新 imq.cluster.brokerlist 和 imq.cluster.masterbroker 特性。

4. 重新啟動叢集中的所有代理程式。

當主代理程式無法使用時

由於叢集中的所有代理程式都需要主代理程式才能執行永久性作業，因此沒有可用的主代理程式時，叢集中所有代理程式的下列 imqcmd 子指令都會傳回錯誤：

• create dst

• destroy dst

• update dst

• destroy dur

自動建立的實體目標和暫時目標不受影響。

在未配置主代理程式的環境中，任何嘗試建立或取消長期訂閱的用戶端應用程式都會收到一個錯誤。但是用戶端可以指定並與現有的長期訂閱進行互動。

第 10 章 監視代理程式

本章描述可用來監視代理程式的工具，以及如何取得度量資料。本章包含下列各小節：

• 監視工具簡介

• 配置及使用代理程式記錄功能

• 以互動方式顯示度量

• 撰寫應用程式來監視代理程式

有關特定度量的參考資訊，請參閱第 18 章, 度量參照。

監視工具簡介

Message Queue^TM 資訊有 3 個監視介面：記錄檔、互動式指令，以及可以取得度量的用戶端 API。各有下列優點和缺點：

• 記錄檔提供長期的度量資料記錄，但是不易剖析。

• 指令可讓您快速取得符合您需求的資訊範例，但無法查看歷程資訊或有計劃的處理資料。

• 用戶端 API 可讓您擷取資訊、處理資訊、處理資料、顯示圖表或傳送警示。然而若要使用它，您必須撰寫自訂應用程式來擷取和分析資料。

表 10–1 對不同的工具進行比較。

除了表格中顯示的差異之外，每個工具所收集之代理程式產生的度量資訊也會稍有不同。如需有關各個監視工具所收集度量資料的詳細資訊，請參閱第 18 章, 度量參照。

配置及使用代理程式記錄功能

Message Queue 記錄程式會取得代理程式程式碼、除錯程式和度量產生器所產生的資訊，並且將這些資訊寫入數個輸出通道：標準輸出 (主控台)、記錄檔，以及 Solaris™ 作業系統上的 syslog 常駐程式程序。

您可以指定記錄程式收集的資訊類型，以及寫入每個輸出通道的類型。要特別注意的是，您可以指定您要寫入記錄檔的度量資訊。

本節描述代理程式的預設記錄配置，並介紹如何將記錄資訊重新導向至替代輸出通道、如何變更記錄檔自動重建準則，以及如何將度量資料傳送到記錄檔。

預設記錄配置

代理程式會自動配置為將記錄輸出儲存到一組自動重建的記錄檔中。這些記錄檔的所在目錄名稱，與相關聯代理程式之實例名稱相同 (請參閱附錄 AMessage Queue^TM 資料的特定平台位置)：

…/instances/instanceName/log

如果代理程式的生命週期由應用程式伺服器所控制，則記錄檔的位置是在啟動該代理程式所在網域的網域目錄子目錄中：

…/appServer_domainName_dir/imq/instances/imqbroker/log

記錄檔為簡單的文字檔案。其命名方式如下 (從最早建立到最新建立)：

log.txt
log_1.txt
log_2.txt
…log_9.txt

依預設，每週自動重建一次記錄檔；而系統會維護 9 個備份檔案。

• 若要變更保留記錄檔的目錄，請將特性 imq.log.file.dirpath 設定為所需的路徑。

• 若要將記錄檔的根名稱從 log 變更為其他名稱，請設定 imq.log.file.filename 特性。

代理程式支援三種記錄層級：ERROR、WARNING 、INFO。表 10–2 解釋各個層級的涵義。

設定某個記錄層級，則會收集此層級以及所有更高層級的訊息。預設記錄層級是 INFO，因此依預設，ERROR、 WARNING 和 INFO 訊息會全部記錄。

記錄訊息格式

記錄的訊息包含時間標記、訊息程式碼和訊息本身。資訊容量因您所設定的記錄層級而有所不同。以下為 INFO 訊息的範例。

[13/Sep/2000:16:13:36 PDT] [B1004]: Starting the broker service using tcp 
[25374,100] with min threads 50 and max threads of 500

若要變更時間標記的時區，請參閱表 14–8 中有關描述 imq.log.timezone 特性的資訊。

變更記錄程式配置

表 14–8 描述記錄的相關特性。

變更代理程式的記錄程式配置

1. 設定記錄層級。

2. 為一個或多個記錄種類設定輸出通道 (檔案和/或主控台)。

3. 如果您將輸出記錄至檔案，請為此檔案配置自動重建準則。

   可以透過設定記錄程式特性來完成這些步驟。您可以用以下兩種方法之一執行此作業：

   • 啟動代理程式之前，請先變更或增加代理程式之 config.properties 檔案中的記錄程式特性。

   • 在啟動代理程式的 imqbrokerd 指令中，指定記錄程式指令行選項。您也可以使用代理程式選項 -D 變更記錄程式特性 (或任何代理程式特性)。

   在指令行上傳送的選項，會置換在代理程式實例配置檔案中所指定的特性。以下的 imqbrokerd 選項會影響記錄：

   -metrics interval

   代理程式度量的記錄時間間隔 (以秒為單位)

   -loglevel level

   記錄層級 (ERROR、WARNING、 INFO 或 NONE)

   -silent

   無訊息模式 (不記錄至主控台)

   -tty

   將所有訊息記錄至主控台

   以下各節描述如何變更預設配置，以執行以下作業：

   • 變更輸出通道 (記錄訊息的目標)

   • 變更自動重建準則

變更輸出通道

依預設，錯誤和警告訊息可顯示在終端機上，也可記錄至記錄檔中。(在 Solaris 上，錯誤訊息也可寫入至系統的 syslog 常駐程式。)

您可以用以下方法變更記錄訊息的輸出通道：

• 若要使所有記錄種類 (對於指定的層級) 輸出顯示在畫面上，請使用 imqbrokerd 指令的 -tty 選項。

• 若要避免記錄輸出顯示在畫面上，請使用 imqbrokerd 指令的 -silent 選項。

• 使用 imq.log.file.output 特性，指定應寫入至記錄檔的記錄資訊種類。例如：

  imq.log.file.output=ERROR

• 使用 imq.log.console.output 特性，指定應寫入至主控台的記錄資訊種類。例如：

  imq.log.console.output=INFO

• 在 Solaris 上，使用 imq.log.syslog.output 特性，指定應寫入至 Solaris syslog 的記錄資訊種類。例如：

  imq.log.syslog.output=NONE

變更記錄程式輸出通道前，您必須確定所設定的記錄層級，支援要對映到輸出通道的資訊。例如，如果您將記錄層級設定為 ERROR，並且將 imq.log.console.output 特性設定為 WARNING，則不會記錄任何訊息，因為您未啟用 WARNING 訊息的記錄。

變更記錄檔自動重建準則

有兩個記錄檔自動重建準則：時間和容量。預設為使用時間準則，每七天自動重建一次檔案。

• 若要變更時間間隔，您需要變更特性 imq.log.file.rolloversecs。例如，以下特性定義將時間間隔變更為十天：

  imq.log.file.rolloversecs=864000

• 若要將自動重建準則變更為取決於檔案容量，您需要設定 imq.log.file.rolloverbytes 特性。例如，以下定義會讓代理程式在檔案達到 500,000 個位元組的限制時，就自動重建檔案。

  imq.log.file.rolloverbytes=500000

如果同時設定與時間相關的自動重建特性以及與容量相關的自動重建特性，則先達到的限制將觸發自動重建作業。如上所述，代理程式最多可保留九個自動重建檔案。

代理程式執行時，您可以設定或變更記錄檔自動重建特性。若要設定這些特性，請使用 imqcmd update bkr 指令。

將度量資料傳送到記錄檔

本節描述使用代理程式記錄檔報告度量資訊的程序。如需有關配置記錄程式的一般資訊，請參閱配置及使用代理程式記錄功能。

使用記錄檔報告度量資訊

1. 配置代理程式的度量產生功能：

   1. 確定 imq.metrics.enabled=true

      依預設，會開啟用於記錄的度量產生功能。

   2. 設定度量產生的合適秒數時間間隔。

      imq.metrics.interval=interval

      您可以在 config.properties 檔案中設定此值，或在啟動代理程式時，使用 -metrics interval 指令行選項設定此值。

2. 確定記錄程式已收集度量資訊：

   imq.log.level=INFO

   這是預設值。啟動代理程式時，您可以在 config.properties 檔案中設定此值，或使用 -loglevel level 指令行選項設定此值。

3. 確定已設定記錄程式，將度量資訊寫入記錄檔：

   imq.log.file.output=INFO

   這是預設值。您可以在 config.properties 檔案中進行設定。

4. 啟動代理程式。

   以下所示為代理程式度量輸出到記錄檔的範例：

   [21/Jul/2004:11:21:18 PDT] Connections: 0 JVM Heap: 8323072 bytes (7226576 free) Threads: 0 (14-1010) In: 0 msgs (0bytes) 0 pkts (0 bytes) Out: 0 msgs (0bytes) 0 pkts (0 bytes) Rate In: 0 msgs/sec (0 bytes/sec) 0 pkts/sec (0 bytes/sec) Rate Out: 0 msgs/sec (0 bytes/sec) 0 pkts/sec (0 bytes/sec)

   如需有關度量資料的參考資訊，請參閱第 18 章, 度量參照。

記錄停用的訊息

您可以啟用代理程式停用的訊息之記錄功能來監視實體目標。無論您有沒有使用此停用的訊息佇列，都可以記錄這些停用的訊息。

啟用此停用的訊息之記錄功能後，代理程式會記錄下列類型的事件：

• 實體目標超出最大容量。

• 代理程式移除實體目標的訊息，原因可能如下：

  • 已達目標容量限制。

  • 訊息的時限已到。

  • 訊息太大。

  • 代理程式處理訊息時發生錯誤。

如果停用的訊息佇列在使用中，還會記錄下列類型的事件：

• 代理程式將訊息移動到停用的訊息佇列。

• 代理程式將停用的訊息佇列中的訊息移除並且捨棄。

以下為停用的訊息之記錄格式範例：

[29/Mar/2006:15:35:39 PST] [B1147]: Message 8-129.145.180.87(e7:6b:dd:5d:98:aa)-
35251-1143675279400 from destination Q:q0 has been placed on the DMQ because 
[B0053]: Message on destination Q:q0 Expired: expiration time 1143675279402, 
arrival time 1143675279401, JMSTimestamp 1143675279400

依預設，不記錄停用的訊息。若要記錄，請設定代理程式屬性 imq.destination.logDeadMsgs。

以互動方式顯示度量

Message Queue 代理程式可以報告下列類型的度量：

• Java 虛擬機器 (JVM) 度量。有關 JVM 堆疊容量的資訊。

• 代理程式通用度量。有關儲存於代理程式中的訊息、輸入和輸出代理程式的訊息流量，以及記憶體用途的資訊。追蹤訊息的數量和位元組數。

• 連線服務度量。有關連線和連線執行緒資源的資訊，以及有關特定連線服務訊息流量的資訊。

• 目標度量。有關傳入和傳出特定實體目標之訊息流量的資訊，以及有關實體目標用戶、記憶體和磁碟空間使用率的資訊。

imqcmd 指令可以取得整個代理程式、個別連線服務和個別實體目標的度量資訊。若要取得度量資料，通常可使用 imqcmd 的子指令 metrics。度量資料會依您指定的時間間隔或次數寫入主控台畫面。

您也可以使用 query 子指令，檢視也包含配置資訊的類似資料。如需更多資訊，請參閱imqcmd query。

imqcmd metrics

imqcmd metrics 的語法和選項分別顯示於表 10–3 和表 10–4 中。

metrics bkr
   [-b hostName:portNumber]
   [-m metricType]
   [-int interval]
   [-msp numSamples]

metrics svc -n serviceName
   [-b hostName:portNumber]
   [-m metricType]
   [-int interval]
   [-msp numSamples]

metrics dst -t destType
   -n destName
   [-b hostName:portNumber]
   [-m metricType]
   [-int interval]
   [-msp numSamples]

-b hostName: portNumber

-int interval

-m metricType

-msp numSamples

-n destName

-n serviceName

-t destType

使用顯示度量資料的 metrics 子指令

本小節描述使用 metrics 子指令報告度量資訊的程序。

使用 metrics 子指令

1. 啟動需要度量資訊的代理程式。

   請參閱啟動代理程式。

2. 發出適當的 imqcmd metrics 子指令和選項，如表 10–3 和表 10–4 中所示。

度量輸出：imqcmd 度量

本小節包含 imqcmd metrics 子指令的輸出範例。這些範例顯示代理程式範圍、連線服務和實體目標度量。

代理程式通用度量

若要取得訊息和封裝每隔 10 秒傳入和傳出代理程式的速率，請使用 metrics bkr 子指令：

imqcmd metrics bkr -m rts -int 10 -u admin

此指令會產生與以下相類似的輸出 (請參閱表 18–2 中的資料說明)：

--------------------------------------------------------
 Msgs/sec   Msg Bytes/sec   Pkts/sec    Pkt Bytes/sec   
 In   Out     In      Out     In   Out     In      Out  
--------------------------------------------------------
 0     0      27      56      0     0      38      66   
 10    0     7365     56      10    10    7457    1132  
 0     0      27      56      0     0      38      73   
 0     10     27     7402     10    20    1400    8459  
 0     0      27      56      0     0      38      73   

連線服務度量

若要取得 jms 連線服務所處理的訊息和資料封包等累積總數，請使用 metrics svc 子指令：

imqcmd metrics svc -n jms -m ttl -u admin

此指令會產生與以下相類似的輸出 (請參閱表 18–3 中的資料說明)：

-------------------------------------------------
  Msgs      Msg Bytes      Pkts      Pkt Bytes     
In   Out    In     Out   In   Out    In     Out  
-------------------------------------------------
164  100  120704  73600  282  383  135967  102127
657  100  483552  73600  775  876  498815  149948

實體目標度量

若要取得有關實體目標的度量資訊，請使用 metrics dst 子指令：

imqcmd metrics dst -t q -n XQueue -m ttl -u admin

此指令會產生與以下相類似的輸出 (請參閱表 18–4 中的資料說明)：

-----------------------------------------------------------------------------
  Msgs      Msg Bytes         Msg Count         Total Msg Bytes (k)     Largest
In   Out    In     Out    Current  Peak  Avg  Current  Peak     Avg    Msg (k)
-----------------------------------------------------------------------------
200  200  147200  147200     0     200    0      0      143      71        0  
300  200  220800  147200    100    200   10     71      143      64        0  
300  300  220800  220800     0     200    0      0      143      59        0  

若要取得有關實體目標的用戶資訊，請使用以下 metrics dst 子指令：

imqcmd metrics dst -t q -n SimpleQueue -m con -u admin

此指令會產生與以下相類似的輸出 (請參閱表 18–4 中的資料說明)：

------------------------------------------------------------------
  Active Consumers         Backup Consumers         Msg Count
Current  Peak  Avg      Current  Peak    Avg    Current  Peak  Avg
------------------------------------------------------------------
   1       1      0        0       0      0       944    1000  525

imqcmd query

表 10–5 中顯示 imqcmd query 的語法和選項，以及該指令所提供之度量資料的說明。

query bkr
   [-b hostName: portNumber]

query svc -n serviceName
  [-b  hostName:portNumber]

query dst -t destType
  -n destName
  [-b hostName:portNumber]

由於 imqcmd query 提供的度量資料有限，因此未在第 18 章, 度量參照的表格中列出此工具。

撰寫應用程式來監視代理程式

Message Queue 提供度量監視功能，此功能可讓代理程式將度量資料寫入 JMS 訊息，然後根據訊息中包含的度量資訊類型，將資料傳送到其中一個度量主題目標。

您可以藉由寫入訂閱度量主題目標、使用目標中的訊息並處理訊息中度量資訊的用戶端應用程式，來存取此度量資訊。

總共有 5 個度量主題目標，表 10–6 中顯示這些目標的名稱，以及應傳送到每個目標的度量訊息類型。

設定訊息型監視

本小節描述使用訊息型監視功能以收集度量資訊的程序。程序包括用戶端部署和管理作業。

若要設定訊息型監視

1. 寫入度量監視用戶端。

   請參閱「Message Queue Developer's Guide for Java Clients」，瞭解如何以程式設計方式讓用戶端訂閱度量主題目標、使用度量訊息，以及從這些訊息擷取度量資料。

2. 設定 config.properties 檔案中的代理程式特性值，以配置代理程式的度量訊息產生者：

   1. 啟用度量訊息產生。

      設定 imq.metrics.topic.enabled=true

      預設為 true。

   2. 設定產生度量訊息的時間間隔 (以秒為單位)。

      設定 imq.metrics.topic.interval=interval。

      預設為 60 秒。

   3. 指定度量訊息是否為永久性訊息 (即訊息是否在代理程式故障後仍然存留)。

      設定 imq.metrics.topic.persist。

      預設為 false。

   4. 指定度量訊息刪除前，保留在其個別目標中的時間長短。

      設定 imq.metrics.topic.timetolive。

      預設值為 300 秒。

3. 設定任何您要在度量主題目標上的存取控制。

   請參閱以下安全性與存取注意事項中的說明。

4. 啟動度量監視用戶端。

   用戶訂閱度量主題時，即會自動建立度量主題目標。建立度量主題之後，代理程式度量訊息產生者就會開始傳送度量訊息到度量主題。

安全性與存取注意事項

有兩個限制度量主題目標存取的原因：

• 度量資料可能包含有關代理程式及其資源的機密資訊。

• 度量主題目標的訂閱數過量，可能會增加代理程式的經常性耗用時間，因此會對效能產生不良影響。

由於這些考量，所以建議您限制度量主題目標的存取。

監視用戶端必須遵守與其他用戶端相同的認證和授權控制。只有 Message Queue 使用者儲存庫中的使用者可以連線到代理程式。

您可以使用存取控制特性檔案來限制對於特定度量主題目標的存取，以提供額外保護，如使用者授權：存取控制特性檔案中所述。

例如，以下 accesscontrol.properties 檔案中的項目會拒絕任何使用者存取 mq.metrics.broker 度量主題，但 user1 和 user 2 除外。

topic.mq.metrics.broker.consume.deny.user=*
topic.mq.metrics.broker.consume.allow.user=user1,user2

以下項目僅允許使用者 user3 監視主題 t1。

topic.mq.metrics.destination.topic.t1.consume.deny.user=*
topic.mq.metrics.destination.topic.t1.consume.allow.user=user3

您也可以根據度量資料的機密程度，使用加密連線將度量監視用戶端連線到代理程式。如需有關使用加密連線的資訊，請參閱訊息加密。

度量輸出：度量訊息

使用訊息型監視 API 取得度量資料輸出，是您編寫度量監視用戶端需具備的功能之一。您僅受限於代理程式中度量產生器提供的資料。如需此資料的完整清單，請參閱第 18 章, 度量參照。

第 11 章 分析與調校訊息服務

本章涵蓋的數個主題，說明如何分析與調校 Message Queue^TM 服務，以便將訊息傳送應用程式的效能最佳化。它包括以下主題：

• 關於效能

• 影響效能的因素

• 調校配置以改善效能

關於效能

本節提供效能調校的一些背景資訊。

效能調校程序

訊息傳送應用程式的效能取決於應用程式和 Message Queue 服務之間的互動。因此，最佳化效能需要應用程式開發者和管理員共同的努力。

最佳化效能的程序從應用程式設計開始，然後是部署應用程式，接著再對訊息服務進行調校。效能調校程序包括以下階段：

• 定義應用程式的效能需求

• 設計應用程式時必須考量影響效能的因素 (特別是可靠性與效能之間的取捨)

• 建立基準效能測量

• 調校或重新配置訊息服務以最佳化效能

以上略述的程序通常是反覆的。在部署應用程式期間，Message Queue 管理員應評估訊息服務是否符合應用程式的一般效能需求。如果效能評定測試符合這些需求，管理員可以根據本章說明調校系統。但是，如果效能評定測試不符合效能需求，則可能需要重新設計應用程式或修改架構部署。

效能類型

一般而言，效能是指訊息服務從產生器傳送訊息到用戶的速度和效率之測量結果。但是，您可能會依您的需要關注效能的不同方面。

連線負載

系統可支援之訊息產生器、訊息用戶或同步運作連線的數目。

訊息流量

每秒導入訊息傳送系統的訊息數目或訊息容量。

延時

從訊息產生器傳送特定訊息到訊息用戶所需的時間。

穩定性

訊息服務的整體可用性，或者在負載量較大或失敗時訊息服務緩慢降低的程度。

效率

訊息傳送的效率，亦即與已使用之運算資源相關的訊息流量測量結果。

通常這些不同方面的效能都相互關聯。如果訊息流量高，則表示訊息不太可能積存於代理程式中；因此，延時時間會比較短 (單一訊息可迅速傳送)。但是，延時可取決於很多因素：通訊連結的速度、代理程式處理速度，以及用戶端處理速度等。

無論如何，會有數個不同方面的效能。對您最重要的方面通常取決於特定應用程式的需求。

效能評定

效能評定是針對訊息傳送應用程式建立測試套件，並且為此測試套件測量訊息流量或其他方面效能的程序。

例如，您可以建立一個測試套件，讓數個訊息產生用戶端使用數個連線、階段作業和訊息產生器，以某個特定速率，將標準容量的永久性或非永久性訊息傳送到數個佇列或主題 (這些都取決於您的訊息傳送應用程式設計)。同樣地，此測試套件包括數個訊息使用用戶端，這些用戶端會使用數個連線和階段作業，以及在測試套件實體目標中以特定確認模式使用訊息的特定類型訊息用戶。

使用標準的測試套件，您可以測量訊息產生和使用間所需的時間或平均訊息流量速率，並且可以監視系統以觀察連線執行緒用法、訊息儲存資料、訊息流量資料和其他相關度量。在效能受到不良影響之前，您就可以迅速增加訊息產生的速率、訊息產生器的數目或其他變數。您可以達到的最大流量為您訊息服務配置的效能評定。

使用此效能評定，您可以修改部分測試套件的特徵。請謹慎控制所有可能影響效能的因素 (請參閱影響效能的應用程式設計因素)，您可以對變更其中某些因素會如何影響效能評定進行記錄。例如，您可以將連線數目或訊息容量增加 5 倍或 10 倍，然後記下效能所受的影響。

反過來，您也可以保持以應用程式為基礎的因素不變，而以某種控制方法變更代理程式配置 (例如，變更連線特性、執行緒池特性、JVM 記憶體限制、限制運作方式、檔案式與 JDBC 型永久性... 等等)，並記錄這些變更對於效能所產生的影響。

應用程式的效能評定會提供資訊，這些資訊在您要藉由調校訊息服務增加已部署應用程式的效能時會有所幫助。效能評定可以更加準確地預測一個變更或一組變更的效果。

一般來說，效能評定應在受控制的測試環境中執行，並且要時間足夠長以讓訊息服務穩定執行。(啟動時，及時 (Just-In-Time) 編譯會將 Java 程式碼轉為機器碼，這會對效能造成不良影響。)

基準使用式樣

部署並執行訊息傳送應用程式之後，請務必建立基準使用式樣。您必須知道尖峰需求出現的時間並可以將需求數目化。例如，需求通常會因一般使用者的數目、作業層級、每天的時間或所有這些因素而有所變化。

若要建立基準使用式樣，您必須長時間監視訊息服務，查看下列資料：

• 連線數目

• 儲存於代理程式中 (或特定實體目標中) 的訊息數目

• 傳入和傳出代理程式 (或特定實體目標) 的訊息流量

• 使用中用戶數目

您還可以使用度量資料中提供的平均值與尖峰值。

檢查這些出乎設計意料之外的基準度量是非常重要的。經由此動作，您會檢查用戶端程式碼是否正常運作：例如，連線未處於開啟狀態，或使用的訊息未處於未確認狀態。這些編碼錯誤會耗用代理程式資源，並且可能對效能有很明顯的影響。

基準使用式樣可幫助您判斷如何將系統調校到最佳化效能。例如：

• 如果某個實體目標的使用頻繁程度比其他實體目標高出許多，則您可能需要將此實體目標的訊息記憶體限制設定得較高，或者據此調整限制行為。

• 如果所需的連線數目明顯大於最大執行緒池容量允許的大小，那麼您可能要增加執行緒池大小，或調校共用執行緒模型。

• 如果尖峰訊息流量遠大於平均流量，則可能會影響您在記憶體不足時使用的限制運作方式。

一般而言，您對使用式樣的瞭解越多，您調校系統用於未來需求的式樣與計劃的能力越好。

影響效能的因素

訊息延時和訊息流量是兩個主要的效能指標，通常取決於一般訊息完成訊息傳送程序的各個步驟所花費的時間。以下顯示的步驟適用於持續可靠傳送訊息的情況。下圖描述這些步驟。

圖 11–1 透過 Message Queue 服務傳送訊息

訊息傳送步驟

1. 訊息由訊息產生用戶端傳送到代理程式。

2. 代理程式讀取訊息。

3. 訊息會置於永久性存放區中，以確保其可靠性。

4. 代理程式確認接收到訊息，以確保其可靠性。

5. 代理程式判斷訊息的路由狀況。

6. 代理程式寫出訊息。

7. 訊息由代理程式傳送到訊息使用用戶端。

8. 訊息使用用戶端確認接收到訊息，以確保其可靠性。

9. 代理程式處理用戶端確認，以確保其可靠性。

10. 代理程式確定已處理用戶端確認。

    由於這些是連續的步驟，因此，在從訊息產生用戶端傳送訊息到使用用戶端時，其中任何步驟都可能成為瓶頸。大部份的步驟都取決於訊息傳送系統的實體特徵：網路頻寬、電腦處理速度、訊息服務架構等。但是，還有些步驟是取決於訊息傳送應用程式的特徵和要求的可靠性層級。

    以下各小節說明應用程式設計因素與訊息傳送系統因素對於效能的影響。當在訊息傳送中應用程式設計和訊息傳送系統因素相互操作時，將單獨考量每個種類。

影響效能的應用程式設計因素

應用程式設計決策會對整體訊息傳送效能產生顯著的效果。

影響訊息傳送可靠性的因素，對效能的影響最為重要。這些因素如下：

• 傳送模式 (永久性/非永久性訊息)

• 作業事件的使用

• 確認模式

• 長期和非長期訂閱

其他影響效能的應用程式設計因素如下：

• 選擇器的使用 (訊息篩選)

• 訊息容量

• 訊息內文類型

以下各小節說明影響訊息傳送效能的以上各個因素。一般來說，要在效能與可靠性之間進行取捨與平衡：提昇可靠性的因素往往會降低效能。

表 11–1 顯示各種應用程式設計因素通常如何影響訊息傳送效能。表格顯示兩種方案 (一個可靠性高但效能低的方案，另一個效能高但可靠性低的方案)，以及每一個方案的應用程式設計因素選擇。在這兩種極端的方案之間，有多種選擇和取捨可影響可靠性和效能。

傳送模式 (永久性/非永久性訊息)

永久性訊息可在代理程式發生故障的情況下，確保訊息傳送。代理程式會在所有預定用戶確認他們已使用訊息前，將訊息儲存在永久性存放區中。

永久性訊息的代理程式處理速度會比非永久性的訊息處理速度慢，原因如下：

• 代理程式必須以可靠的方式儲存永久性訊息，以便在代理程式發生故障時，才不會遺失永久性訊息。

• 代理程式必須確認每個永久性訊息的接收。一旦產生訊息的方法未傳回異常，就確保會傳送至代理程式。

• 代理程式可能需要確定訊息使用用戶端對於永久性訊息的確認，依用戶端的確認模式而定。

對於佇列以及長期訂閱者的主題而言，處理非永久性訊息的效能大約快 40%。我們是使用容量為 10k 的訊息和 AUTO_ACKNOWLEDGE 模式取得這些結果。

作業事件的使用

作業事件可確保在已處理的階段作業中產生的所有訊息以及使用的所有訊息，都會分別當成一個單位予以處理或不處理 (回復)。

Message Queue 支援本機作業事件和分散式作業事件。

已處理的階段作業中產生或確認訊息的速度，會比在未處理階段作業中的速度慢，原因如下：

• 附加資訊必須隨每個產生訊息一起儲存。

• 某些狀況會儲存作業事件中通常不需要儲存的訊息 (例如，傳送到未訂閱主題目標的永久性訊息通常會遭到刪除，但是在作業事件開始時，有關訂閱的資訊還無法取得)。

• 作業事件中的訊息使用和確認資訊，必須在確定作業事件時進行儲存和處理。

確認模式

一種確保 JMS 訊息可靠傳送的機制，用戶端會確認 Message Queue 代理程式所傳送的訊息已被使用。

如果在用戶端尚未確認訊息時關閉階段作業，或在處理確認前代理程式發生故障，則代理程式會重新傳送訊息，並設定 JMSRedelivered 旗標。

對於未處理的階段作業而言，用戶端可以選擇三種確認模式中的一種，而每一種模式都具有各自的效能特徵：

• AUTO_ACKNOWLEDGE。一旦用戶處理訊息後，系統會自動確認訊息。此模式可確保提供者發生故障後最多會重新傳送一次訊息。

• CLIENT_ACKNOWLEDGE。此應用程式會控制確認訊息的端點。確認先前的確認後，所有訊息會在該階段作業中進行處理。在處理一組確認時，如果代理程式發生故障，則會重新傳送群組中一個或多個訊息。

• DUPS_OK_ACKNOWLEDGE。此模式引導系統在惰性狀態下確認訊息。提供者發生故障後，可以重新傳送多個訊息。

(使用 CLIENT_ACKNOWLEDGE 模式與使用作業事件相似，但如果在處理期間提供者發生故障，則前者不確保會一併處理所有的確認。)

確認模式影響效能的原因如下：

• 在 AUTO_ACKNOWLEDGE 和 CLIENT_ACKNOWLEDGE 模式中，代理程式與用戶端之間需要有額外的控制訊息。額外控制訊息會增加額外的處理經常性耗用時間，並且可能會干擾 JMS 有效負載訊息，因而造成處理延遲。

• 在 AUTO_ACKNOWLEDGE 和 CLIENT_ACKNOWLEDGE 模式中，用戶端必須等待代理程式確定已處理用戶端的確認，才能夠使用其他訊息。(代理程式的此項確認作業可確保代理程式不會意外重新傳送這些訊息。)

• 必須以用戶所接收全部永久性訊息的確認資訊來更新 Message Queue 永久性存放區，因此會降低效能。

長期和非長期訂閱

主題目標的訂閱者分為兩類：長期訂閱者和非長期訂閱者。

長期訂閱可提高可靠性，但會降低流量速度，原因如下：

• Message Queue 訊息服務必須永久儲存指定到每個長期訂閱的訊息清單，以便當代理程式發生故障時，可在回復後使用此清單。

• 長期訂閱的永久性訊息會永久儲存，以便於當代理程式發生故障時，仍然可以在代理程式回復後，於對應的用戶成為使用中狀態時重新傳送訊息。相反的，非長期訂閱的永久性訊息不會永久儲存 (一旦代理程式故障，對應用戶的連線會中斷，而且不會重新傳送訊息)。

我們以兩個狀況比較長期訂閱者與非長期訂閱者的效能：容量為 10k 的永久性和非永久性訊息。這兩種狀況都使用 AUTO_ACKNOWLEDGE 確認模式。只有在永久性訊息的狀況下，長期訂閱的效能才會受到影響 (總共降低了大約 30%)。

選擇器的使用 (訊息篩選)

應用程式開發者通常會將訊息組指向特定用戶。他們會藉由將每個訊息組指向唯一實體目標，或使用單一實體目標並為用戶註冊一個或多個選擇器，以達成此目的。

選擇器是一個字串，請求僅將包含符合此字串特性值的訊息傳送到特定用戶。例如，選擇器 NumberOfOrders >1 僅會傳送包含 NumberOfOrders 特性值 2 或更高值的訊息。

使用選擇器建立用戶會降低效能 (與使用多個實體目標比較)，因為每個訊息都需要額外的處理。使用選擇器時必須剖析選擇器，如此一來，選擇器可與之後的訊息相符合。此外，在路由每個訊息時，必須擷取每個訊息的訊息特性並與選擇器進行比較。但是，使用選擇器可在訊息傳送應用程式中提供更多彈性。

訊息容量

因為必須將更多資料從訊息產生用戶端傳送到代理程式，以及從代理程式傳送到訊息使用用戶端，而且對於永久性訊息，必須儲存較大的訊息，所以訊息容量會影響效能。

但是，藉由將較小訊息批次到單一訊息，可以最小化個別訊息的路由和處理，以改善整體效能。在此情況下，會遺失個別訊息狀態的相關資訊。

在我們的測試中，將傳送至佇列目標的容量為 1k、10k 和 100k 之訊息的流量 (以 KB/秒為單位) 相互比較 (使用 AUTO_ACKNOWLEDGE 確認模式)；我們發現，非永久性訊息傳送在傳送 1k 訊息時大約快 50%，10k 訊息時大約快 20%，100k 訊息時大約快 5%。訊息容量會明顯影響永久性和非永久性訊息。100k 訊息大約是 10k 的 10 倍快，10k 大約是 1k 的 5 倍快。

訊息內文類型

JMS 支援 5 種訊息內文類型，依複雜性大致排列如下：

• BytesMessage 包含一組位元組，其格式由應用程式所決定。

• TextMessage 是一個簡單的 Java 字串。

• StreamMessage 包含一串 Java 原始值。

• MapMessage 包含一組「名稱-值」對。

• ObjectMessage 包含一個 Java 串列化物件。

雖然通常狀況下，使用何種訊息類型是依應用程式的需求而定，但是更複雜的類型 (MapMessage 和 ObjectMessage ) 會增加效能耗用：因為對資料進行串列化和取消串列化作業會消耗效能。效能耗用取決於資料簡單或複雜的程度。

影響效能的訊息服務因素

訊息傳送應用程式的效能不只受到應用程式設計的影響，也受到執行訊息路由和傳送的訊息服務影響。

以下各節介紹可影響效能的這種訊息服務因素。瞭解這些因素的影響，是增減訊息服務功能、診斷和解決已部署應用程式中可能會出現之效能瓶頸的關鍵。

影響 Message Queue 服務效能的最重要因素如下：

• 硬體

• 作業系統

• Java 虛擬機器 (JVM)

• 連線

• 代理程式限制和運作方式

• 訊息服務架構

• 資料存放區效能

• 用戶端執行階段配置

以下各小節說明影響訊息傳送效能的以上各個因素。

硬體

對於 Message Queue 代理程式和用戶端應用程式而言，CPU 處理速度和可用記憶體是決定訊息服務效能的主要因素。增加處理能力可以減少許多軟體限制，而增加記憶體可以同時增加處理速度和能力。然而，升級硬體以克服這些瓶頸通常需要一筆花費。

作業系統

因為不同作業系統的效率也不同，因此即便是相同的硬體平台，效能也會各有差異。例如，作業系統使用的執行緒模型，對於代理程式可支援的同步運作之連線數目會有重大影響。一般而言，在全部硬體都相同的狀況下，Solaris 系統通常比 Linux 系統快，而 Linux 系統通常比 Windows 系統快。

Java 虛擬機器 (JVM)

代理程式是在主機 JVM 中執行且受其支援的 Java 處理程序。因此，JVM 處理是決定代理程式路由和傳送訊息的速度和效率的重要因素。

尤其是，JVM 的記憶體資源管理相當重要。必須為 JVM 配置足夠的記憶體，以因應增加的記憶體負載。另外，JVM 會定期收回未使用的記憶體，而記憶體收回作業會延遲訊息處理。JVM 記憶體堆疊越大，記憶體收回過程中可能的延遲時間就越長。

連線

用戶端和代理程式之間的連線數目和速度，會影響訊息服務可處理的訊息數目以及訊息傳送的速度。

代理程式連線限制

所有對代理程式的存取都透過連線進行。對於同步運作之連線數目的任何限制，都會影響目前可同時使用代理程式的訊息產生用戶端或訊息使用用戶端的數目。

與代理程式的連線數目，通常會受到可用執行緒數目的限制。您可以將 Message Queue 配置為支援專用的執行緒模型，或是支援共用的執行緒模型 (請參閱執行緒池管理)。

專用執行緒模型的執行速度非常快，因為每個連線都有專用執行緒；但是，連線數目受到可用執行緒數目的限制 (每個連線都使用一個輸入執行緒和一個輸出執行緒)。共用執行緒模型在連線數目上沒有限制；但是，在連線數目超過共用執行緒時，會產生明顯的經常性耗用時間和流量延遲，特別是在連線忙碌時。

傳輸協定

Message Queue 軟體可讓用戶端使用各種低層級的傳輸協定，與代理程式進行通訊。Message Queue 支援連線服務中描述的連線服務 (以及對應的協定)。

協定是根據應用程式需求 (加密、可透過防火牆存取) 而選擇的，但是所選擇的結果會影響整體效能。

圖 11–2 傳輸協定速度

我們的測試比較了 TCP 和 SSL 在兩種狀況下的流量：高可靠性方案 (將 1K 的永久性訊息傳送到包含長期訂閱的主題目標，並且使用 AUTO_ACKNOWLEDGE 確認模式)，和高效能方案 (將 1K 的非永久性訊息傳送到不包含長期訂閱的主題目標，並且使用 DUPS_OK_ACKNOWLEDGE 確認模式)。

一般而言，我們發現協定對於可靠性高的方案影響較小。這可能是因為，在可靠性高的方案中，所需要的永久性經常性耗用時間是限制流量的更重要因素，其影響比協定速度的影響更大。另外：

• TCP 提供與代理程式進行通訊的最快速方法。

• 傳送和接收訊息時，SSL 的速度比 TCP 慢了 50% 到 70% (如果是永久性訊息則慢了 50%；非永久訊息則慢了將近 70%)。此外，使用 SSL 建立初始連線的速度較慢 (可能會花費數秒)，因為用戶端和代理程式 (若為 HTTPS，則是 Web 伺服器) 需要建立私密金鑰以供加密所傳輸的資料時所使用。由於加密和解密每個低層級 TCP 資料封包都需要進行額外處理，因此效能會降低。

• HTTP 的速度比 TCP 或 SSL 慢。HTTP 將在 Web 伺服器上執行的 Servlet 當做用戶端與代理程式之間的代理。將資料封包封裝為 HTTP 請求，以及訊息必須通過兩個躍點 (用戶端至 Servlet、Servlet 至代理程式) 才能到達代理程式，都會影響效能的經常性耗用時間。

• HTTPS 的速度比 HTTP 慢，因為 HTTPS 需要額外的經常性耗用時間以加密用戶端與 Servlet 之間以及 Servlet 與代理程式之間的資料封包。

訊息服務架構

Message Queue 訊息服務可實作為單一代理程式，或實作為包含多個互連代理程式實例的叢集。

隨著連線至代理程式的用戶端數目增加，以及要傳送的訊息數目增加，代理程式最終會超過資源限制，例如，檔案描述元、執行緒和記憶體限制。因應負載增加的方法之一是，將多個代理程式實例增加至 Message Queue 訊息服務，從而在多個代理程式之間分發用戶端連線與訊息路由和傳送。

一般而言，如果用戶端 (尤其是訊息產生用戶端) 在叢集中均勻分布，如此延伸的效果會最好。由於經常性耗用時間受到叢集中代理程式間訊息傳送的影響，所以具有連線數目限制或訊息傳送速率限制的叢集，其表現效能可能會比單一代理程式低。

您還可以使用代理程式叢集來最佳化網路頻寬。例如，您可以在叢集中的一組遠端代理程式間使用速度較慢、距離較長的網路連結，而使用較高速度的連結將用戶端連線至其各自的代理程式實例。

如需有關叢集的更多資訊，請參閱第 9 章, 使用代理程式叢集。

代理程式限制和運作方式

代理程式可能需要處理的訊息流量，是代理程式所支援之訊息傳送應用程式使用式樣的一個函數。然而，代理程式在資源上受到限制：記憶體、CPU 週期... 等等。因此，代理程式可能會在超過限制時當機，造成沒有回應或不穩定的狀況。

Message Queue 訊息代理程式有內建機制，可管理記憶體資源，並預防代理程式耗盡記憶體。這些機制的可配置限制包括代理程式可保留的訊息數目和訊息容量、其個別實體目標，以及達到實體目標限制時可採取的運作方式。

透過謹慎的監視與調校，使用這些可配置的機制以平衡傳入和傳出訊息的流量，這樣就不會發生系統超載的狀況。這些機制會消耗經常性耗用時間並限制訊息流量，但他們會維護作業完整性。

資料存放區效能

Message Queue 支援檔案式與 JDBC 型永久性模組。檔案式永久性使用個別的檔案來儲存永久性資料。JDBC 型永久性使用 Java 資料庫連結 (JDBC™) 介面，並且需要 JDBC 相容的資料存放區。檔案型永久性通常快於 JDBC 型永久性；但是，某些使用者偏好 JDBC 相容存放區所提供的備援和管理控制。

在使用檔案式永久性的情況下，您可以指定永久性作業同步化包含資料存放區的常駐記憶體狀態，以保持最佳可靠性。這可以消除因系統當機而產生的資料遺失，但會影響效能。

用戶端執行階段配置

Message Queue 用戶端執行階段為用戶端應用程式提供 Message Queue 訊息服務的介面。它支援用戶端將訊息傳送至實體目標和從此類目標接收訊息所需的所有作業。設定連線工廠屬性值就能夠配置用戶端執行階段，讓您控制它在改善效能與訊息流量等方面的運作方式，例如連線流量測量、用戶流量限制與連線流量限制。如需有關這些功能、以及用來配置這些功能的屬性之更多資訊，請參閱用戶端執行階段訊息流量調校。

調校配置以改善效能

以下各小節說明配置調整如何影響效能。

系統調校

以下各小節描述您可對作業系統、JVM 和通訊協定所做的調整。

Solaris 調校：CPU 使用、分頁/交換/磁碟 I/O

請參閱您系統的文件來調校您的作業系統。

Java 虛擬機器調整

依預設，代理程式會使用 192MB 的 JVM 堆疊容量。此容量對大量的訊息負載通常過小，所以應增加其大小。

當代理程式將要耗盡 Java 物件使用的 JVM 堆疊儲存區空間時，會使用各種技術 (如流量控制和訊息交換) 來釋放記憶體。在極端情況下，它甚至會關閉用戶端連線以釋放記憶體，並降低訊息的傳入量。因此，最好將最大 JVM 堆疊儲存區空間設定得足夠大，以避免發生此類情況。

但是，如果將最大 Java 堆疊儲存區空間設定得過大 (相對於系統實體記憶體)，代理程式會持續增加 Java 堆疊儲存區空間，直至整個系統的記憶體用完。這會導致效能降低、不可預料的代理程式當機，和/或影響系統上執行的其他應用程式和服務的運作。一般而言，您需要允許足夠用於作業系統和機器上其他執行應用程式的實體記憶體。

一般而言，最好先評估正常時段和尖峰時段的系統記憶體使用量，然後再配置 Java 堆疊容量，該容量大小應足以提供良好的效能，但又不至於大到導致系統記憶體問題。

若要變更代理程式的最小和最大堆疊容量，請在啟動代理程式時，使用 -vmargs 指令行選項。例如：

/usr/bin/imqbrokerd -vmargs "-Xms256m -Xmx1024m"

此指令會將 Java 堆疊容量的下限設定為 256MB，上限為 1GB。

• 在 Solaris 或 Linux 上，如果經由 /etc/rc* (也就是 /etc/init.d/imq) 啟動代理程式，則請在 /etc/imq/imqbrokerd.conf (Solaris) 或 /etc/opt/sun/mq/imqbrokerd.conf (Linux) 檔案中，指定代理程式指令行引數。請查看檔案中的註解，以取得更多資訊。

• 在 Windows 上，如果將代理程式當成 Windows 服務啟動，則請使用 -vmargs 選項，將 JVM 引數指定到 imqsvcadmin install 指令。請參閱第 13 章, 指令行參照中的服務管理員公用程式。

在任何狀況下，都請檢查代理程式的記錄檔或使用 imqcmd metrics bkr -m cxn 指令，以驗證設定。

調校傳輸協定

選擇符合應用程式需求的協定後，可進行額外調校 (以選取的協定為基礎) 以改善效能。

以下 3 個代理程式特性可用來修改協定效能：

• imq.protocol.protocolType .nodelay

• imq.protocol.protocolType .inbufsz

• imq.protocol.protocolType .outbufsz

對於 TCP 和 SSL 協定，這些特性會影響用戶端和代理程式之間訊息傳送的速度。對於 HTTP 和 HTTPS 協定，這些特性會影響 Message Queue 通道 Servlet (在 Web 伺服器上執行) 和代理程式之間訊息傳送的速度。HTTP/HTTPS 協定還有其他會影響效能的特性 (請參閱HTTP/HTTPS 調校)。

將會在以下各節描述協定調校特性。

nodelay

nodelay 特性會影響用於指定協定的 Nagle 演算法 (TCP/IP 上 TCP_NODELAY 傳輸層選項的值)。Nagle 演算法可用以改善使用慢速連線 (例如廣域網路 (WAN) 等) 之系統上的 TCP 效能。

使用該演算法時，TCP 會將資料包裝為較大的資料封包，從而避免傳送一些小的資料塊到遠端系統。如果寫入套接的資料未填滿所需緩衝區大小，那麼協定會在緩衝區填滿或特定延遲時間結束前，延遲傳送封包。一旦緩衝區填滿或發生逾時，即會傳送資料封包。

對於大部份的訊息傳送應用程式，如果傳送資料封包時沒有延遲 (未啟用 Nagle 演算法)，則效能為最佳。這是因為用戶端與代理程式之間大部份都是請求/回應式互動：用戶端傳送資料封包給代理程式且等待回應。例如，典型的互動包括：

• 建立連線

• 建立產生器或用戶

• 傳送永久性訊息 (代理程式會確定已接收訊息)

• 在 AUTO_ACKNOWLEDGE 或 CLIENT_ACKNOWLEDGE 階段作業中傳送用戶端確認 (代理程式會確定確認處理)

對於這些互動，大部份的資料封包都小於緩衝區大小。這表示，如果使用 Nagle 演算法，則代理程式在傳送回應到用戶之前，會延遲數毫秒。

但是，在連線速度緩慢和不需代理程式回應的狀況下，Nagle 演算法可改善效能。例如，在用戶端傳送非永久性訊息，或用戶端的確認未經代理程式確定 (DUPS_OK_ACKNOWLEDGE 階段作業) 等狀況下。

inbufsz/outbufsz

inbufsz 特性會設定輸入串流上的緩衝區大小，輸入串流可讀取來自通訊端的資料。同樣地，outbufsz 會設定輸出串流上的緩衝區大小，輸出串流由代理程式用來將資料寫入通訊端。

一般而言，兩個參數值皆應稍微大於接收或傳送的平均封包容量。根據經驗，請將這些特性值設定為比平均資料封包容量多 1 KB (四捨五入至最接近的以 KB 為單位之整數值)。例如，如果代理程式接收內文容量為 1 KB 的資料封包，則該封包 (訊息內文加上標頭和特性) 的總容量約為 1.2 KB；inbufsz 為 2 KB (2048 個位元組) 即可提供適當的效能。將 inbufsz 或 outbufsz 增加到超過此容量可能會稍微改善效能，但是將增加各個連線所需的記憶體。

HTTP/HTTPS 調校

除了前面兩小節描述的一般特性之外，HTTP/HTTPS 效能受限於用戶端發出 HTTP 請求到託管 Message Queue 通道 Servlet 之 Web 伺服器的速度。

Web 伺服器可能需要最佳化，以處理單一通訊端上的多個請求。從 JDK 1.4 版或更新版本開始，HTTP 與 Web 伺服器的連線會持續作用 (到 Web 伺服器的通訊端會保持開啟)，以便在 Web 伺服器處理多個 HTTP 請求時，將 Web 伺服器使用的資源降到最低。在相同用戶端應用程式上使用 JDK 1.4 版的效能，如果比使用較早 JDK 版本的效能低，則您可能需要調校 Web 伺服器持續作用的配置參數，以改善效能。

除了對 Web 伺服器進行此類調校，您也可以調整用戶端輪詢 Web 伺服器的頻率。HTTP 是請求型協定。這表示，使用 HTTP 型協定的用戶端會定期檢查 Web 伺服器，以查看是否有等待中的訊息。imq.httpjms.http.pullPeriod 代理程式特性 (以及類似的 imq.httpsjms.https.pullPeriod 特性) 會指定 Message Queue 用戶端執行階段輪詢 Web 伺服器的頻率。

如果 pullPeriod 值為 -1 (預設值)，則用戶端執行階段會在前一個請求傳回時立即輪詢伺服器，以便最有效發揮個別用戶端的效能。因此，各個用戶端連線均會獨占 Web 伺服器中的一個請求執行緒，因而可能會過度使用 Web 伺服器資源。

如果pullPeriod 值為正數，則用戶端執行階段會定期傳送請求到 Web 伺服器，以查看是否有擱置的資料。在此狀況下，用戶端不會獨占 Web 伺服器中的請求執行緒。因此，如果大量用戶端使用 Web 伺服器，則您可能需要將 pullPeriod 設定為正值，以節省 Web 伺服器資源。

調校檔案式永久性存放區

如需有關調校檔案式永久性存放區的資訊，請參閱永久性服務。

代理程式調校

以下各小節描述您可如何調整代理程式特性以改善效能。

記憶體管理：在代理程式負載過重時提高穩定性

您可以對每個目標個別配置記憶體管理，或是集中配置整個系統層級 (針對所有目標) 的記憶體管理。

使用實體目標限制

如需有關實體目標限制的資訊，請參閱第 6 章, 管理實體目標。

使用系統範圍限制

如果訊息產生器經常使訊息用戶超載，代理程式中可能會累積訊息。代理程式包含一個在記憶體不足情況下，降低產生器速度和將訊息移出使用中記憶體的機制，所以對代理程式可保留的訊息總數目 (和訊息容量) 做出硬式限制是明智之舉。

設定 imq.system.max_count 和 imq.system.max_size 代理程式特性，可控制這些限制。

例如：

imq.system.max_count=5000

以上定義的值，表示代理程式最多只會保留 5000 個未傳送/未確認的訊息。如果傳送額外訊息，則會被代理程式拒絕。如果為永久性訊息，那麼產生器在嘗試傳送訊息時會發生異常。如果為非永久性訊息，代理程式會直接丟棄訊息。

當傳送訊息時傳回異常，用戶端應稍作暫停並試著再傳送一次。(請注意，永遠不會因為代理程式接收訊息失敗而發生異常；所發生的異常都是由傳送端的用戶端所偵測到的異常。)

多重用戶佇列效能

多個佇列用戶在佇列目標中處理訊息的效率，取決於下列可配置的佇列目標屬性：

• 使用中的用戶數目 (maxNumActiveConsumers)

• 單一批次中可傳送到用戶的最大訊息數目 (consumerFlowLimit)

若要達到最佳的訊息流量，必須有充足的使用中用戶數目以滿足佇列產生訊息的速率，並且將佇列中的訊息路由並傳送到使用中用戶時，必須能讓使用的速率達到最快。「Sun Java System^TM Message Queue 技術摘要」中描述平衡多個用戶上訊息傳送的一般機制。

如果訊息累積在佇列中，那麼使用中用戶數目可能會不足以處理訊息負載。也有可能發生以下情形：以批次大小傳送到用戶的訊息會在用戶上進行備份。例如，如果批次大小 (consumerFlowLimit) 過大，一個用戶可能會接收佇列中的所有訊息，而其他使用中用戶則收不到任何訊息。如果用戶處理速度非常快，這可能不會發生問題。

但是，如果用戶的速度相對較慢，那麼您必須將訊息平均分發給用戶，如此一來，批次大小也會變小。批次大小越小，傳送訊息至用戶所需的經常性耗用時間就越長。然而，針對處理速度慢的用戶，網路效能改善比率通常會使用小型的批次大小。

用戶端執行階段訊息流量調校

本小節將討論影響效能的流量控制運作方式 (請參閱用戶端執行階段配置)。請將這些運作方式配置為連線工廠受管理物件的屬性。如需有關設定連線工廠屬性的資訊，請參閱第 8 章, 管理受管理物件。

訊息流量計數

用戶端傳送和接收的訊息 (有效負載訊息) 與 Message Queue 控制訊息，都會透過用戶端與代理程式之間的相同連線進行傳送。如果有效負載訊息的傳送阻擋了控制訊息，則會造成控制訊息 (例如代理程式確認) 延遲傳送。若要避免此擁塞狀況，Message Queue 會計算連線上的有效負載訊息流量。

有效負載訊息分為多個批次 (如連線工廠屬性 imqConnectionFlowCount 所指定)，因此只傳送已設定數目的有效負載訊息。批次傳送後，會暫停傳送有效負載訊息，而只傳送擱置的控制訊息。接著傳送其他有效負載訊息，然後傳送擱置控制訊息，重複此循環。

如果用戶端正在進行需要代理程式大量回應的作業，則 imqConnectionFlowCount 的值應保持較低：例如，如果用戶端正在使用 CLIENT_ACKNOWLEDGE 或 AUTO_ACKNOWLEDGE 模式、永久性訊息、作業事件或佇列瀏覽器，或者正在新增或移除用戶。而另一方面，如果用戶端在連線上只有簡易用戶，並且使用 DUPS_OK_ACKNOWLEDGE 模式，則您可以增加 imqConnectionFlowCount 的值，而不會影響效能。

訊息流量限制

在達到本機資源限制 (例如記憶體限制) 之前，Message Queue 用戶端執行階段可處理的有效負載訊息數目也會有所限制。到達此限制時，會對效能造成影響。因此，Message Queue 會限制每個用戶 (或每個連線) 在連線中傳送的訊息數目，以及在用戶端執行階段中進行緩衝以等待使用的訊息數目。

用戶流量限制

如果傳送到用戶端執行階段的有效負載訊息數超過了為任何用戶所設定的 imqConsumerFlowLimit 值，則會停止傳送訊息給該用戶。只有在傳送給該用戶的未使用訊息數低於此 imqConsumerFlowThreshold 設定值時，才會重新繼續傳送訊息。

以下範例說明這些限制的使用：考量主題用戶的設定值：

imqConsumerFlowLimit=1000
imqConsumerFlowThreshold=50

建立用戶時，代理程式會不間斷傳送第一批 1000 個訊息 (假設存在這些訊息) 給該用戶。傳送這 1000 個訊息之後，代理程式會停止傳送，直到用戶端執行階段要求傳送更多訊息。應用程式處理這些訊息前，用戶端執行階段會保留這些訊息。在要求代理程式傳送下一個批次之前，用戶端執行階段會允許應用程式使用至少 50% (imqConsumerFlowThreshold) 的訊息緩衝容量 (即 500 個訊息)。

在相同情況下，如果臨界值為 10%，則在要求傳送下一個批次之前，用戶端執行階段會等待應用程式至少使用 900 個訊息。

以下計算下一個批次的大小：

imqConsumerFlowLimit - (current number of pending msgs in buffer)

因此，如果imqConsumerFlowThreshold 為 50%，則下一個批次大小可介於 500 到 1000 之間，其實際數量取決於應用程式處理訊息的速度。

如果 imqConsumerFlowThreshold 設定過高 (接近 100%)，則代理程式會嘗試傳送較小的批次，以降低訊息流量。如果該值過低 (接近 0%)，則在代理程式傳送下一組批次之前，用戶端也許能完成處理其餘的緩衝訊息，這也會造成訊息流量下降。一般而言，除非您有特定的效能或可靠性考量，否則不需要變更 imqConsumerFlowThreshold 屬性的預設值。

用戶型流量控制 (尤其是 imqConsumerFlowLimit ) 是管理用戶端執行階段中記憶體的最佳方法。通常，根據用戶端應用程式，您會知道您在任何連線上需要支援的用戶數目、訊息容量和可用於用戶端執行階段的總記憶體容量。

連線流量限制

然而，在一些用戶端應用程式中，用戶數目可能是不確定的，它取決於一般用戶的選擇。在此情況下，您仍可以使用連線層級流量限制來管理記憶體。

連線層級流量控制可限制連線上所有用戶的緩衝訊息總數。如果此數目超過 imqConnectionFlowLimit 的值，則會停止透過連線傳送訊息，直到總數目低於連線限制為止。(只有將 imqConnectionFlowLimitEnabled 設定為 true，才會啟用 imqConnectionFlowLimit 屬性。)

階段作業中形成佇列的訊息數目為使用階段作業之用戶數目及用於每個用戶之訊息負載的函數。如果用戶端在產生和使用訊息中發生延遲，通常您可以藉由重新設定應用程式，以分發較大階段作業數目上的訊息產生器和用戶，或者分發較大連線數目上的階段作業，並因此改善效能。

第 12 章 排解疑難問題

本章說明如何瞭解及解決下列問題：

• 用戶端無法建立連線

• 連線流量過慢

• 用戶端無法建立訊息產生器

• 訊息產生延遲或過慢

• 儲存訊息

• 代理程式的流量不穩定

• 訊息未送達用戶

• 停用的訊息佇列包含訊息

發生問題時，檢查所安裝 Message Queue^TM 軟體的版本編號，通常很有幫助。版本編號可讓您確定所用文件的編號是否與軟體版本相符。向 Sun 報告問題時，也需要版本編號。若要檢查版本編號，請發出以下指令：

imqcmd -v

用戶端無法建立連線

徵兆：

• 用戶端無法建立新的連線。

• 用戶端無法自動重新連線失敗的連線。

可能原因：

• 用戶端應用程式未關閉連線，導致連線數目超過資源限制

• 未執行代理程式或網路連結發生問題

• 連線服務不在使用中或已暫停

• 可用於所需連線數目的可用執行緒太少

• Solaris 或 Linux 平台上要求用於連線數目的檔案描述元太少

• TCP 積存區會限制可同時新建連線請求的數目

• 作業系統限制同步運作中連線的數目

• 使用者的認證或授權失敗

可能原因：用戶端應用程式未關閉連線，導致連線數目超過資源限制。

若要確認此問題的原因：列出代理程式的所有連線：

imqcmd list cxn

輸出會列出所有連線和建立每個連線的主機，從而瞭解哪些用戶端開啟了過多的連線。

若要解決此問題：重新寫入違例用戶端，以關閉不使用的連線。

可能原因：未執行代理程式或網路連結發生問題。

若要確認此問題的原因：

• 使用 Telnet 連線至代理程式主要連接埠 (例如，預設的 7676 連接埠)，並透過連接埠對映器的輸出來驗證代理程式是否作出回應。

• 驗證代理程式程序是否在主機上執行。

若要解決此問題：

• 啟動代理程式。

• 修復網路連結問題。

可能原因：連線服務不在使用中或已暫停。

若要確認此問題的原因：檢查所有連線服務的狀態：

imqcmd list svc

如果連線服務狀態顯示為 unknown 或 paused，則用戶端無法使用該服務建立連線。

若要解決此問題：

• 如果連線服務狀態顯示為 unknown，此服務不會顯示在使用中服務的清單 (imq.service.active) 上。在 SSL 型服務中，服務也可能會配置錯誤，造成代理程式在代理程式記錄中產生以下項目：

  ERROR [B3009]: Unable to start service ssljms: [B4001]: Unable to open protocol tls for ssljms service...

  此項目後面是發生異常的基本原因說明。

  若要正確配置 SSL 服務，請參閱訊息加密。

• 如果連線服務狀態顯示為 paused，請重新繼續該服務 (請參閱暫停和重新繼續連線服務)。

可能原因：可用於所需連線數目的可用執行緒太少。

若要確認此問題的原因：檢查代理程式記錄中的以下項目：

WARNING [B3004]: No threads are available to process a new connection on service ... Closing the new connection.

並且使用下列其中一種格式，檢查連線服務上的連線數目，以及目前使用中的執行緒數目：

imqcmd query svc -n serviceName imqcmd metrics svc -n serviceName -m cxn

每個連線均需要 2 個執行緒：一個用於內送訊息，另一個用於外寄訊息 (請參閱執行緒池管理)。

若要解決此問題：

• 如果您使用專用執行緒池模型 (imq. serviceName.threadpool_model= dedicated)，那麼最大的連線數目是執行緒池中最大執行緒數目的一半。因此，若要增加連線數目，請增加執行緒池的容量 (imq. serviceName.max_threads)，或改為使用共用執行緒池模型。

• 如果您使用共用執行緒池模型 (imq. serviceName.threadpool_model=shared)，那麼最大的連線數目是連線監視限制 (imq.serviceName.connectionMonitor_limit ) 與最大執行緒數目 (imq. serviceName.max_threads) 積的一半。因此，若要增加連線數目，請增加執行緒池的大小或增加連線監視限制。

• 可支援的連線數目 (或連線上的流量) 最終會達到輸入/輸出限制。在此情況下，請使用多代理程式叢集，以分發叢集中代理程式實例上的連線。

可能原因：Solaris 或 Linux 平台上要求用於連線數目的檔案描述元太少。

如需有關此問題的更多資訊，請參閱設定檔案描述元限制。

若要確認此問題的原因：檢查代理程式記錄中是否有以下相似項目：

Too many open files

若要解決此問題：增加檔案描述元限制，如 ulimit 線上手冊所述。

可能原因：TCP 積存區會限制可同時新建連線請求的數目。

TCP 積存區會限制同時儲存在系統積存區內的連線請求數目 (imq.portmapper.backlog )，連接埠對映器會在超過此限制之後拒絕其他請求。(Windows 平台上有程序內定的積存區限制：Windows 個人版作業系統的數目限制為 5 個，Windows 伺服器版作業系統的數目為 200 個。)

因為不會經常出現同時有大量的連線請求，所以因儲存區限制的請求拒絕通常為短暫現象。

若要確認此問題的原因：檢查代理程式記錄。首先，檢查代理程式在拒絕其他連線的同時是否有接受某些連線。接著，檢查拒絕連線的說明訊息。如果找到這類訊息，可能不是 TCP 積存區的問題，因為代理程式不會記錄 TCP 積存區造成的拒絕連線。如果記錄中有成功的連線，但是未記錄任何拒絕連線，則可能是 TCP 積存區的問題。

若要解決此問題：

• 將用戶端設定成每隔一小段時間就重試連線 (此方法通常可行，因為這是暫時性的問題)。

• 增加 imq.portmapper.backlog 的值。

• 檢查用戶端關閉和開啟連線的次數是否過於頻繁。

可能原因：作業系統限制同步運作中連線的數目。

Windows 作業系統授權會限制所支援的同步運作遠端連線的數目。

若要確認此問題的原因：檢查可用於連線的執行緒數目是否夠用 (使用 imqcmd query svc)，並檢查 Windows 授權合約的條款。如果您是從本地用戶端建立連線，而不是從遠端用戶端，作業系統限制可能是造成此問題的原因。

若要解決此問題：

• 升級 Windows 授權，以允許更多的連線。

• 設定多代理程式叢集，以分發一些代理程式實例的連線。

可能原因：使用者的認證或授權失敗。

認證可能因為下列任一原因而失敗：

• 密碼不正確

• 使用者儲存庫中沒有使用者的項目

• 使用者沒有存取連線服務的權限

若要確認此問題的原因：檢查代理程式記錄中是否有 Forbidden 錯誤訊息的項目。這表示有驗證錯誤，但不表示為問題發生的原因。

• 如果您使用檔案式使用者儲存庫，請輸入以下指令：

  imqusermgr list -i instanceName -u userName

  如果輸出顯示有使用者，則可能是提交了錯誤的密碼。如果輸出顯示下列錯誤，則使用者儲存庫中沒有該使用者的任何項目：

  Error [B3048]: User does not exist in the password file

• 如果您使用 LDAP 伺服器使用者儲存庫，請使用適當的工具檢查是否有使用者的任何項目。

• 檢查存取控制特性檔案，查看是否有存取連線服務的限制。

若要解決此問題：

• 如果使用的密碼錯誤，請提供正確的密碼。

• 如果使用者儲存庫中沒有使用者的任何項目，請增加一個項目 (請參閱寫入和管理使用者儲存庫)。

• 如果使用者沒有存取連線服務的權限，請編輯存取控制特性檔案以授予這類權限 (請參閱連線服務的存取控制)。

連線流量過慢

徵兆：

• 訊息流量未符合預期速度。

• 支援連線至代理程式的數目並未如用戶端無法建立連線中所述受到限制，而是因為訊息輸入/輸出速率受到限制。