|
| |
| Sun Java System Message Queue 3 2005Q4 管理指南 | |
第 5 章
管理代理程式本章說明如何使用 imqcmd 公用程式來管理代理程式及其服務。本章包含下列各節：
本章未包含有關管理代理程式的所有相關主題。下列幾章包含其他主題：
- 在代理程式上管理實體目標。如需有關如何建立、顯示、更新及銷毀實體目標，和如何使用停用的訊息佇列等主題的資訊，請參閱第 6 章「管理實體目標」。
- 設定代理程式的安全性。如需有關使用者認證、存取控制、加密、密碼檔案和稽核記錄等主題的資訊，請參閱第 7 章「管理安全性」。
必要條件您可以使用 imqcmd 和 imqusermgr 指令行公用程式來管理代理程式。管理代理程式前，請先執行以下作業：
- 使用 imqbrokerd 公用程式指令啟動代理程式。代理程式執行後，才能使用其他指令行公用程式。
- 決定要設定 Message Queue 管理使用者或使用預設帳號。您必須指定使用者名稱和密碼，才能使用管理指令。
當您安裝 Message Queue 時，同時也安裝了預設平面檔案使用者儲存庫。此儲存庫出廠時隨附兩個預設項目：管理使用者和 guest 使用者。測試 Message Queue 時，您可以使用預設使用者名稱和密碼 (admin/admin) 來執行 imqcmd 公用程式。
設定生產系統時，必須設定認證及授權管理使用者。如需設定檔案型使用者儲存庫或配置使用 LDAP 目錄伺服器的詳細資訊，請參閱第 7 章「管理安全性」。在生產環境中使用非預設使用者名稱和密碼，較為安全。
- 如果您要與代理程式使用安全連線，請在目標代理程式實例上設定並啟用 ssladmin 服務。如需更多資訊，請參閱使用 SSL 型服務。
使用 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。在生產環境中應該使用自訂使用者名稱。
指定密碼
您可以使用下列任一方法指定密碼：
舊版 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
提示您輸入密碼後，指令會輸出類似下面的內容：
更新代理程式特性您可以使用 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 選項，指定下列一種要顯示的度量類型：
使用 -int 選項，指定顯示度量的間隔時間 (以秒為單位)。預設為 5 秒鐘。
使用 -msp 選項，指定輸出中顯示的範例數目。預設的數目為沒有限制 (無限)。
例如，若要取得每 10 秒時間間隔，代理程式傳入與傳出的訊息速率，請使用：
imqcmd metrics bkr -m rts -int 10 -u admin
此指令的輸出如下：
--------------------------------------------------------
訊息/秒鐘 訊息容量/秒鐘 Pkts /秒鐘 Pkt 位元組/秒鐘
輸入 輸出 輸入 輸出 輸入 輸出 輸入 輸出
--------------------------------------------------------
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) 和基本傳輸協定相關。
表 5-1 代理程式支援的連線服務
服務名稱
服務類型
協定類型
jms
NORMAL
tcp
ssljms (Enterprise Edition)
NORMAL
tls (SSL 型安全性)
httpjms (Enterprise Edition)
NORMAL
http
httpsjms (Enterprise Edition)
NORMAL
https (SSL 型安全性)
admin
ADMIN
tcp
ssladmin (Enterprise Edition)
ADMIN
tls (SSL 型安全性)
您可以使用 imqcmd 子指令來管理整個連線服務，或管理個別連線服務。如果子指令的目標是個別服務，請使用 -n 選項，以表 5-1 之 [服務名稱] 欄位中所列的名稱之一進行指定。
列出連線服務
若要列出代理程式上可用的連線服務，請使用 list svc 子指令。
list svc 子指令的語法如下：
imqcmd list svc [-b hostName:portNumber]
該子指令列出預設代理程式或指定主機和連接埠上的代理程式上的所有連線服務。
以下指令列出在使用連接埠 7676 的 localhost 上執行的代理程式上的所有服務：
imqcmd list svc -u admin
此指令將輸出以下資訊：
------------------------------------------------
服務名稱 連接埠號 服務狀態
------------------------------------------------
admin 41844 (動態) 執行中
httpjms - 未知
httpsjms - 未知
jms 41843 (動態) 執行中
ssladmin 動態 未知
ssljms 動態 未知
顯示連線服務資訊
若要查詢並顯示單一服務的相關資訊，請使用 query 子指令。
query svc 子指令的語法如下：
imqcmd query svc -n serviceName [-b hostName:portNumber]
query svc 子指令會顯示在預設代理程式或指定主機和連接埠的代理程式上所執行的指定服務之相關資訊。
例如：
imqcmd query svc -n jms -u admin
提示您輸入密碼後，指令會輸出類似下面的內容：
更新連線服務特性
您可以使用 update 子指令變更表 5-2 中所列出的一個或多個服務特性的值。
表 5-2 imqcmd 更新的連線服務特性
特性
說明
port
指定給要更新的服務之連接埠 (不適用於 httpjms 或 httpsjms)。0 值表示連接埠對映器會動態配置連接埠。
minThreads
指定給服務的執行緒之最小數量。
maxThreads
指定給服務的最大執行緒數目。
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 選項指定要顯示的度量類型：
使用 -int 選項，指定顯示度量的間隔時間 (以秒為單位)。預設為 5 秒鐘。
使用 -msp 選項，指定輸出中顯示的範例數目。預設的數目為沒有限制 (無限)。
例如，若要取得由 jms 連線服務處理之訊息和封包的累計總數，請使用：
imqcmd metrics svc -n jms -m ttl -u admin
提示您輸入密碼後，指令會輸出類似下面的內容：
-------------------------------------------------
訊息 訊息容量 Pkts Pkt 位元組
輸入 輸出 輸入 輸出 輸入 輸出 輸入 輸出
-------------------------------------------------
164 100 120704 73600 282 383 135967 102127
657 100 483552 73600 775 876 498815 149948
如需使用 imqcmd 報告連線服務度量的更多詳細說明，請參閱連線服務度量。
暫停和繼續連線服務
若要暫停管理服務 (無法暫停) 之外的任何服務，請使用 pause svc 和 resume svc 子指令。
pause svc 子指令的語法如下：
imqcmd pause svc -n serviceName [-b hostName:portNumber]
該子指令暫停在預設代理程式或指定主機和連接埠上代理程式執行的指定服務。例如，下列指令會暫停預設代理程式上所執行的 httpjms 服務。
imqcmd pause svc -n httpjms -u admin
暫停服務會造成以下影響：
若要繼續服務，請使用 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
提示您輸入密碼後，指令會輸出類似下面的內容：
列出以下指定的代理程式上所有連線：
-----------------------------------
主機 主要連接埠
------------------------------------
localhost 7676
---------------------------------------------------------------------------
連線 ID 使用者 服務 產生者 用戶 主機
---------------------------------------------------------------------------
1964412264455443200 guest jms 0 1 127.0.0.1
1964412264493829311 admin admin 1 1 127.0.0.1
成功地列出連線。
若要查詢並顯示單一服務的相關資訊，請使用 query 子指令。
query cxn -n connectionID [-b hostName:portNumber]
該子指令會顯示在預設代理程式或指定主機和連接埠之代理程式上，指定連線的相關資訊。
例如：
imqcmd query cxn -n 421085509902214374 -u admin
提示您輸入密碼後，指令會輸出類似下面的內容：
管理長期訂閱您可以執行下列一項或多項作業，使用 imqcmd 子指令來管理代理程式的長期訂閱：
長期訂閱是指由用戶端註冊為長期的主題訂閱；它具有唯一的身份，並要求代理程式保留此訂閱的訊息 (即使它的用戶成為非使用中的用戶)。通常，代理程式僅在為持久訂閱者保留的訊息過期時，才刪除該訊息。
若要列出指定實體目標的長期訂閱，請使用 list dur 子指令。list dur 子指令的語法如下：
imqcmd list dur -d destName
例如，下列指令使用本地主機之預設連接埠上執行的代理程式，列出主題 SPQuotes 的所有長期訂閱：
imqcmd list dur -d SPQuotes
對於主題的每個長期訂閱，list dur 子指令會傳回長期訂閱的名稱、使用者的用戶端 ID、在此主題上形成佇列的訊息數目以及長期訂閱的狀態 (使用中/非使用中)。例如：
名稱 用戶端 ID 訊息 長期訂閱
數目 狀態
----------------------------------------------------------------
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 txn 子指令的語法如下：
imqcmd list txn
例如，以下指令列出代理程式中的所有作業事件。
imqcmd list txn
對於每個作業事件，list 子指令會傳回作業事件 ID、狀態、使用者名稱、訊息或確認的數目以及建立時間。例如：
---------------------------------------------------------------
事務處理 ID 狀態 使用者名稱 訊息數目/ 建立時間
回應數目
---------------------------------------------------------------
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
用戶端 ID
連線
guest@192.18.116.219:62209->jms:62195
建立時間
1/30/02 10:08:31 AM
確認數目
0
訊息數目
4
狀態
PREPARED
作業事件 ID
64248349708800
使用者名稱
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 狀態的作業事件。