|
| Sun ONE Message Queue, Version 3.0.1 管理員指南 |
安裝 Sun™ ONE Message Queue (MQ) 之後，您可以使用 imqbrokerd 指令啟動代理程式。代理程式實例的配置由一組配置檔案和使用 imqbrokerd 指令傳送的選項管理，這些選項置換配置檔案中的相應屬性。
本章介紹 imqbrokerd 指令的語法，以及如何使用指令行選項和配置檔案來配置代理程式實例。此外，還描述如何執行以下作業：
- 編輯代理程式實例配置檔案
- 使用代理程式叢集
- 控制代理程式的記錄
如需如何啟動與使用作為 Windows 服務的代理程式的描述，請參閱將代理程式用作 Windows 服務。
配置檔案
已安裝的配置檔案 (用於配置代理程式) 位於以下目錄。
IMQ_HOME/lib/props/broker
(在 Solaris 上為 /usr/share/lib/imq/props/broker)此目錄儲存以下檔案：
- 啟動時載入的預設配置檔案。此檔案名為 default.properties，並且不可編輯。您可能需要閱讀此檔案，以確定預設設定並找到您要變更之屬性的確切名稱。
- 包含安裝 MQ 時指定的所有屬性的安裝配置檔案。此檔案名為 install.properties；安裝之後無法編輯。
此外，當您首次執行代理程式時，會建立實例配置檔案，您可以用來指定代理程式實例的配置屬性。此檔案由代理程式實例維護以回應管理指令，如果您很仔細也可以直接編輯它。此實例配置檔案儲存在以下位置：
IMQ_VARHOME/instances/代理程式名稱/props/config.properties
(在 Solaris 上為 /var/imq/instances/代理程式名稱/props/config.properties)其中代理程式名稱為代理程式實例的名稱 (依預設為 imqbroker)。您可以編輯實例配置檔案以變更配置 (請參閱編輯實例配置檔案)。
如果您連線叢集中的代理程式實例 (請參閱多重代理程式叢集 (企業版))，您可能還需要使用叢集配置檔案以指定叢集配置資訊。如需更多資訊，請參閱叢集配置屬性。
合併屬性值
啟動時，系統會合併不同配置檔案中的屬性值。它使用在安裝和實例配置檔案中設定的值置換在預設配置檔案中指定的值。您可以透過使用 imqbrokerd 指令選項置換結果值。此機制在圖 5-1 中有說明。
圖 5-1 代理程式配置檔案
屬性命名語法
配置檔案中的任何 MQ 屬性定義均使用以下命名語法：
propertyName=值[[,值 1]...]
例如，以下項目為自動建立佇列定義佇列類型：
imq.queue.default=single
以下項目定義訊息的逾期值：
imq.message.expiration.timeout=90
表格 5-1 以字母順序列出代理程式配置屬性 (及其預設值)。
編輯實例配置檔案
首次執行代理程式實例時，會自動建立 config.properties 檔案。您可以編輯此實例配置檔案，以自訂相應代理程式實例的運作方式和資源使用。
代理程式實例僅在啟動時讀取 config.properties 檔案。若要永久性變更 config.properties 檔案，您可以
- 使用管理工具。如需有關可使用 imqcmd 設定之屬性的資訊，請參閱表格 6-5。
- 當代理程式實例關閉時編輯 config.properties 檔案；然後重新啟動此實例。(在 Solaris 和 Linux 平台上，僅首次啟動此代理程式實例的使用者有權編輯 config.properties 檔案。)
表格 5-1 以字母順序列出代理程式實例配置屬性 (及其預設值)。如需有關每種屬性的涵義和使用的更多資訊，請參閱指定的交叉參照部分。
啟動代理程式
啟動代理程式實例可使用 imqbrokerd 指令。
註 您無法使用管理主控台 (imqadmin) 或指令公用程式 (imqcmd) 啟動代理程式實例。代理程式實例必須已處於執行狀態，才能使用這些 MQ 管理工具。
若要置換一個或多個屬性值，請指定有效的 imqbrokerd 指令行選項。指令行選項可置換代理程式配置檔案中的值，但僅用於目前的代理程式階段作業：指令行選項不能寫入至實例配置檔案。
imqbrokerd 指令的語法如下 (選項和引數用空格分隔)：
imqbrokerd [[ -Dproperty=value]...]
[ -backup fileName]
[ -cluster "[broker] [[,broker]...]"
[ -dbuser userName] [ -dbpassword password]
[ -force]
[ -h]
[ -javahome path | -jrehome path]
[ -ldappassword password]
[ -license name]
[ -loglevel level]
[ -metrics number]
[ -name brokerName ] [ -port number]
[ -shared]
[ -password keypassword] [ -passfile fileName]
[ -remove instance]
[ -reset data]
[ -restore fileName]
[ -shared]
[ -silent] [ -tty]
[ -version] [ -vmargs arg [[arg]...]
例如，若要啟動使用預設代理程式名稱與配置的代理程式，請使用以下指令：
imqbrokerd
此指令可在本地機器上啟動代理程式的預設實例 (名為 imqbroker)，連接埠對映器位於連接埠 7676。
註 在 Solaris 上，您可以將代理程式配置為異常結束後自動重新啟動，方法為透過將 /etc/imq/imqborkerd.conf 配置檔案中的 RESTART 屬性設定為 YES。
註 在 Solaris 和 Linux 平台上，包含配置資訊和永久性資料的目錄的許可權，取決於首次啟動代理程式實例的使用者的身份。因此，若要使代理程式實例運行正常，以後也必須僅由原來的使用者啟動它。
表格 5-2 描述了 imqbrokerd 指令的選項，還描述了每個選項影響的配置屬性 (如果有)。
表格 5-2 imqbrokerd 選項
選項
影響的屬性
描述
-backup fileName
無影響的屬性。
僅適用於代理程式叢集。將主代理程式的配置變更記錄備份至指定檔案。請參閱備份主代理程式的配置變更記錄。
-cluster"[broker]
[[,broker]...]"
broker 為以下之一將 imq.cluster.brokerlist 設定為與其連線的代理程式清單。
僅適用於代理程式叢集。連線至指定主機和連接埠上的所有代理程式。此清單已與 imq.cluster.brokerlist 屬性中的清單合併。如果您沒有為主機指定值，則使用 localhost。如果您沒有為連接埠指定值，則使用值 7676。請參閱使用叢集 (企業版)，以獲得有關如何使用此選項連線多重代理程式的更多資訊。
-dbpassword password
將 imq.persist.jdbc.password 設定為指定的密碼。
為外掛 JDBC 相容資料儲存區指定密碼。請參閱附錄 A「設定外掛持續性」。
-dbuser fileName
將 imq.persist.jdbc.user設定為指定的使用者名稱。
為外掛 JDBC 相容資料庫指定使用者名稱。請參閱附錄 A「設定外掛持續性」。
-Dattribute=value
設定系統屬性。置換實例配置檔案中的相應屬性值。
將指定的屬性設定為指定的值。請參閱表格 5-1，以獲得代理程式配置屬性。
小心：請仔細檢查使用 D 選項設定的屬性的拼寫與格式。如果您傳送了錯誤的值，系統將不警告您，並且 MQ 亦無法設定這些值。
-force
無影響的屬性。
未經使用者確認即執行動作。此選項僅適用於 -remove instance 選項，此選項通常要求確認。
-h
無影響的屬性。
顯示說明。不執行指令行上的其他任何指令。
-javahome path
無影響的屬性。
指定替代 Java 2 相容 JDK 的路徑。預設為使用隨附的運行時間。
-jrehome path
無影響的屬性。
指定 Java 2 JRE 的路徑。
-ldappassword
密碼
將 imq.user_repository.ldap.password 設定為指定的密碼。
為存取 LDAP 使用者儲存庫指定密碼。請參閱將 LDAP 伺服器用於使用者儲存庫。
-license [name]
無影響的屬性。
如果要載入的授權與 MQ 產品版本預設的授權不同，則指定要載入的授權。如果您尚未指定授權名稱，則此項會列出系統上安裝的所有授權。依據已安裝的 MQ 版本，名稱的值為 pe (平台版 — 基本功能)、try (平台版 — 90 天試用企業功能) 和 unl (企業版)。請參閱產品版本。
-loglevel level
將 imq.broker.log.level 設定為指定的級別。
將記錄級別指定為以下之一：NONE、ERROR、WARNING 或 INFO。預設值為 INFO。如需更多資訊，請參閱記錄程式。
-metrics integar
將 imq.metrics.report.interval 設定為指定的秒數。
指定報告標準資訊的間隔時間 (以秒為單位)。
-name brokerName
將 imq.instancename 設定為指定的名稱。
指定此代理程式的實例名稱，並使用相應的實例配置檔案。如果您沒有指定代理程式名稱，則將此檔案的名稱設定為 imqbroker。
註：如果您在同一主機上執行代理程式的多個實例，則每個實例必須具有唯一的名稱。-passfile fileName
將 imq.passfile.enabled 設定為 true。
將 jmq.passfile.dirpath 設定為包含此檔案的路徑。
將 imq.passfile.name 設定為此檔案的名稱。指定檔案的名稱，您可從此檔案讀取 SSL 鍵值儲存區、LDAP 使用者儲存庫或 JDBC 相容資料庫的密碼。如需更多資訊，請參閱使用密碼檔案。
-password keypassword
將 imq.keystore.password 設定為指定的密碼。
為 SSL 證書鍵值儲存區指定密碼。如需更多資訊，請參閱安全性管理程式。
-port number
將 imq.portmapper.port 設定為指定的號碼。
指定代理程式的連接埠對映器連接埠號。依預設，此項設定為 7676。若要在同一伺服器上執行代理程式的兩個實例，則每個代理程式的連接埠對映器必須具有不同的連接埠號。JMS 用戶端使用此連接埠號連線至代理程式實例。
-remove instance
無影響的屬性。
移除代理程式實例：刪除此實例配置檔案、日誌當、永久性儲存區以及與此實例相關聯的其他檔案和目錄。要求使用者確認，除非也指定了 -force 選項。
-reset store| messages|
durables|
props
無影響的屬性。
依據給定的引數，重設資料儲存區 (或資料儲存區的子集) 或代理程式實例的配置屬性。
重設資料儲存區，清除所有永久性資料，包括永久性訊息、持久訂閱和異動資訊。此項可讓您啟動沒有記錄的代理程式實例。您還可以僅清除所有永久性訊息或僅清除所有持久訂閱。(如果您不想在後續的啟動中重設永久性儲存區，請重新啟動未使用 -reset 選項的代理程式實例。)如需更多資訊，請參閱持續性管理程式。
重設代理程式的屬性，用空白檔案取代現有實例配置檔案 (config.properties)：所有屬性均假設為預設值。
-restore fileName
無影響的屬性。
僅適用於代理程式叢集。用指定的備份檔案取代主代理程式的配置變更記錄。此檔案必須已使用 -backup 選項事先建立。請參閱復原主代理程式的配置變更記錄。
-shared
將 imq.jms.threadpool_model 設定為 shared。
指定要使用共用執行緒儲存區模型實施的 jms 連線服務，在此模型中，執行緒在各連線之間共用以增加代理程式實例支援的連線數量。如需更多資訊，請參閱連線服務。
-silent
將 imq.log.console.output 設定為 NONE。
關閉對主控台的記錄。
-tty
將 imq.log.console.output 設定為 ALL。
指定所有訊息均在主控台顯示。依預設，僅顯示 WARNING 和 ERROR 級別的訊息。
-version
無影響的屬性。
顯示安裝產品的版本編號。
-vmargs arg [[arg ]...]
無影響的屬性。
指定要傳送至 Java VM 的引數。用空格分隔各引數。如果您要傳送多個引數，或者如果引數包含空格，請使用括起的引號。例如：
imqbrokerd -tty -vmargs "-Xmx128m -Xincgc"使用叢集 (企業版)
本節描述用於配置多重代理程式叢集的屬性以及連線代理程式的兩種方法，並介紹如何管理叢集。如需叢集的介紹，請參閱多重代理程式叢集 (企業版)。
當使用叢集時，請確保叢集中所有代理程式的主機時鐘同步。
叢集配置屬性
當您將代理程式連線至叢集時，所有連線的代理程式必須為叢集配置屬性指定相同的值。這些屬性描述了叢集中代理程式的參與情況。表格 5-3 總結了與叢集相關的配置屬性。
您可以使用以下兩種方法之一設定叢集屬性：
- 您可以在每個代理程式的實例配置檔案中 (或在啟動每個代理程式的指令行中)，設定與叢集相關的配置屬性。例如，若要連線代理程式 A (在 host1 上，連接埠為 7676)、代理程式 B (在 host2 上，連接埠為 5000) 和代理程式 C (在 ctrlhost 上，連接埠為 7676)，則用於代理程式 A、B 和 C 的實例配置檔案需要設定以下屬性。
imq.cluster.brokerlist=host1, host2:5000, ctrlhost
如果您決定變更叢集配置，則此方法要求更新所有代理程式中與叢集相關的屬性。
- 您可以在一個中央叢集配置檔案中設定叢集配置屬性。這些屬性可能包括要連線的代理程式清單 (imq.cluster.brokerlist)，以及選擇性地包括主代理程式 (imq.cluster.masterbroker) 的位址。
如果您使用此方法，您還必須將 imq.cluster.url 屬性 (對於叢集中的每個代理程式) 設定為指向叢集配置檔案的位置。從易於維護的角度看，此方法為叢集配置的建議方法。
以下程式碼範例顯示叢集配置檔案的內容。host1 與 ctrlhost 均正在預設連接埠上執行。這些屬性指定 host1 與 ctrlhost 均在叢集中連線，並且 ctrlhost 為主代理程式。
imq.cluster.brokerlist=host1,host2:5000,ctrlhost
imq.cluster.masterbroker=ctrlhost
用於在叢集中連線的每個代理程式的實例配置檔案，必須還包含此叢集配置檔案的 URL；例如：
imq.cluster.url=file:/home/cluster.properties
連線代理程式
本節描述將代理程式連線至叢集的兩種方法。無論您使用哪種方法，您啟動的每個代理程式每 5 秒鐘將嘗試連線至其他代理程式；一旦此叢集中的其他代理程式啟動，嘗試即可成功。
如果將代理程式連線至叢集，則不必先啟動主代理程式。如果叢集中有代理程式先於主代理程式啟動，則此代理程式將保持暫停狀態，從而拒絕用戶端連線。當主代理程式啟動時，暫停的代理程式的全部功能將自動可用。
方法 1：無叢集配置檔案
將代理程式連線至叢集
- 使用啟動代理程式的 imqbrokerd 指令的 -cluster 選項，並將代理程式 (要連線的) 的完整清單指定為 -cluster 選項的引數。
- 對於每個要連線至叢集的代理程式，在啟動它時執行此作業。
例如，以下指令啟動新的代理程式，並將其連線至在 host1 的預設連接埠上執行的代理程式、在 host2 的連接埠 7677 上執行的代理程式以及在本地主機的連接埠 7678 上執行的代理程式。
imqbrokerd -cluster host1,host2:7677,:7678
方法 2：使用叢集配置檔案
還可以建立叢集配置檔案，此檔案指定要連線的代理程式清單 (和選擇性地指定主代理程式的位址)。這種定義叢集的方法更適合用於生產系統。請記住，叢集中的每個代理程式均必須將 imq.cluster.url 屬性的值設定為指向此叢集配置檔案。
將代理程式新增至叢集
一旦您已設定代理程式叢集，您可能需要新增新的代理程式或重新啟動此叢集中已存在的代理程式。
若要將新的代理程式新增至現有叢集，您可以執行以下作業之一：
如果您未使用叢集配置檔案，則啟動新代理程式時，使用 -D 選項在指令行上指定 imq.cluster.brokerlist 屬性和 (如有必要) imq.cluster.masterbroker 屬性。
使用叢集配置檔案時將代理程式新增至叢集
- 將此新代理程式新增至叢集配置檔案中的 imq.cluster.brokerlist 屬性。
- 向叢集中的所有代理程式發出以下指令。
imqcmd reload cls
此指令強制所有代理程式重新載入 imq.cluster.brokerlist 屬性，並確保此叢集中代理程式的所有永久性資訊均為最新的。
重新啟動叢集中的代理程式
若要重新啟動已是叢集成員的代理程式，您可以執行以下作業之一：
- 如果已使用叢集配置檔案定義了叢集，則使用 -D 選項在用於啟動代理程式的指令行上指定 imq.cluster.url 屬性。
- 如果未使用叢集配置檔案定義叢集，則啟動新代理程式時，使用 -D 選項在指令行上指定 imq.cluster.brokerlist 屬性 (如有必要指定 imq.cluster.masterbroker 屬性)。如果叢集不包括主代理程式，則啟動新代理程式時，您可以僅使用 -cluster 選項指定叢集中的代理程式清單。
從叢集中移除代理程式
從叢集中移除代理程式時，請注意以下內容：
- 如果代理程式 A、B 和 C 均使用以下指令行啟動，則僅重新啟動 A 將不會從叢集中移除 A。
imqbrokerd -cluster A,B,C
然而，您需要使用以下指令行重新啟動所有其他代理程式：
imqbrokerd -cluster B,C
然後，您需要啟動代理程式 A 而不指定 -cluster 選項。
- 如果已使用叢集配置檔案指定代理程式清單，則您將需要執行以下作業：
備份主代理程式的配置變更記錄
每個叢集可以具有一個主代理程式，以記錄此叢集之永久性狀態的所有變更：其中包括持久訂閱和管理員建立的實體目標。所有代理程式在啟動期間參考主代理程式，以使有關這些永久性物件的資訊同步。因此，主代理程式發生故障可使整個叢集損壞。所以，透過使用 imqbrokerd 指令的 -backup 選項，定期備份主代理程式的變更記錄很重要。例如，
imqbrokerd -backup mybackuplog
適時地進行備份很重要。復原很舊的備份可能會導致資訊遺失：在最新的備份之前建立的所有永久性物件都將遺失。
復原主代理程式的配置變更記錄
在發生故障的情況下復原主代理程式
- 關閉叢集中的所有代理程式。
- 使用以下指令復原主代理程式的配置變更記錄：
imqbrokerd -restore mybackuplog
- 如果您為主代理程式指定了新的名稱或連接埠號，您必須更新叢集配置檔案，以指定此主代理程式是此叢集的一部分並指定其新的名稱 (使用屬性 imq.cluster.masterbroker)。
- 重新啟動所有代理程式。
復原代理程式必將導致某些舊資料重新載入代理程式的配置變更記錄；但是，經常定期備份 (如上節所述) 應可儘量避免此問題。
由於主代理程式記錄永久性物件變更的整個歷程，因此其資料庫可能會在一段時期內迅速增長。備份與復原作業可以有效地壓縮和最適化此資料庫。
記錄
本節描述代理程式的預設記錄配置，並介紹如何變更此配置以便將日誌資訊重新導向至替代輸出通道，以變更捲動條件並報告代理程式標準資訊。如需記錄的介紹，請參閱記錄程式。
預設記錄配置
當您啟動代理程式時，它會自動配置為將日誌輸出儲存至一組捲動的日誌檔中，這些日誌檔位於
IMQ_VARHOME/instances/代理程式名稱/log/
(在 Solaris 上為 /var/imq/instances/代理程式名稱/log/)日誌檔為簡單的文字檔案。它們命名如下，從最舊的到最新的：
log.txt
log_1.txt
log_2.txt
...
log_9.txt依預設，日誌檔每週捲動一次；系統保留九個備份檔案。
- 若要變更保留日誌檔的目錄，請將屬性 imq.log.file.dirpath 設定為所需路徑。
- 若要將日誌檔的根名稱從 log 變更為其他名稱，請設定 imq.log.file.filename 屬性。
代理程式支援三種日誌種類：ERROR、WARNING 和 INFO (請參閱表格 2-7)。設定記錄級別可收集此級別以下 (含此級別) 的所有訊息。預設日誌級別為 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
變更記錄程式配置
表格 2-8 中描述了所有記錄程式屬性。
變更代理程式的記錄程式配置
- 設定日誌級別。
- 為一個或多個記錄種類設定輸出通道 (檔案、主控台或二者)。
- 如果您將輸出記錄至檔案，請為此檔案配置捲動條件。
您可以透過設定記錄程式屬性完成這些步驟。您可以用以下兩種方法之一執行此作業：
- 在啟動代理程式之前，為其變更或新增 config.properties 檔案中的記錄程式屬性。
- 在啟動代理程式的 imqbrokerd 指令中，指定記錄程式指令行選項。您還可以使用代理程式選項 -D 變更記錄程式屬性 (或任何代理程式屬性)。
在指令行上傳送的選項置換在代理程式實例配置檔案中指定的屬性。表格 5-4 列出了影響記錄的 imqbrokerd 選項。
以下各節描述如何變更預設配置以便執行以下作業：
- 變更輸出通道 (日誌訊息的目標)
- 變更捲動條件
- 日誌代理程式標準資訊
變更輸出通道
依預設，錯誤和警告訊息既可在終端機上顯示，也可記錄至日誌檔。(在 Solaris 上，錯誤訊息還可寫入至系統的系統日誌常駐程式。)
您可以用以下方法變更日誌訊息的輸出通道：
- 若要使所有日誌種類 (對於給定的級別) 輸出顯示在畫面上，請使用 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 系統日誌的記錄資訊的種類。例如，
變更捲動條件
有兩個條件用於捲動日誌檔：時間和容量。預設為使用時間條件，每七天捲動一次檔案。
- 若要變更時間間隔，您需要變更屬性 imq.log.file.rolloversecs。例如，以下屬性定義將時間間隔變更為十天：
imq.log.file.rolloversecs=864000
- 若要將捲動條件變更為取決於檔案容量，您需要設定 imq.log.file.rolloverbytes 屬性。例如，以下定義使代理程式在檔案達到 500,000 位元組的限制時，捲動檔案。
imq.log.file.rolloverbytes=500000
如果您同時設定了與時間相關的和與容量相關的屬性，則先達到的限制將啟動捲動。如上所述，代理程式最多可保留九個捲動檔案。
記錄代理程式效能標準資訊
代理程式的預設配置包括以下設定：
- imq.metrics.enabled=true
- imq.metrics.interval=0
- imq.log.level=INFO
由於這些設定，代理程式可為代理程式和作用中的連線服務收集效能標準資訊，但是它不會產生標準資訊報告。
您可以用以下兩種方法之一讓代理程式產生標準資訊報告：
- 使用 imqbrokerd 指令的 -metrics 選項，並指定代理程式產生報告的間隔時間 (以秒為單位)。
- 將 imq.metrics.interval 屬性設定為您想讓代理程式產生報告的間隔時間 (以秒為單位)。
因為 INFO 種類中包括標準資訊報告，所以依預設，標準資訊報告寫入至日誌檔輸出通道。
以下顯示標準資訊範例：
[31/Jan/2001:15:00:50 PST]
Connections:0 JVM Heap:6291456 bytes (5186320 free)
In:0 mesgs (0bytes) 0 pkts (0 bytes)
Out:0 mesgs (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)
表格 5-5 描述了為每種連線服務產生的標準資訊的涵義。
表格 5-6 描述了為每個代理程式收集和報告的標準資訊。
表格 5-6 為每個代理程式收集的標準資訊
標準資訊
描述
VM 堆疊容量 (位元組)
Java VM 堆疊的最大容量。
VM 堆疊自由空間 (位元組)
Java VM 堆疊中剩餘的自由空間容量。
註 透過 imqcmd metrics 指令也可取得此資訊。