第 5 章 管理代理程式
本章說明如何使用 imqcmd 公用程式以管理代理程式及其服務。本章包含下列各節：
本章未包含有關管理代理程式的所有相關主題。下列幾章包含其他主題：
-
在代理程式上管理實體目標。如需有關如何建立、顯示、更新和銷毀實體目標，以及如何使用停用的訊息佇列等主題的資訊，請參閱第 6 章, 管理實體目標。
-
設定代理程式的安全性。如需有關使用者認證、存取控制、加密、密碼檔案和稽核記錄等主題的資訊，請參閱第 7 章, 管理安全性。
必要條件
您可以使用 imqcmd 和 imqusermgr 指令行公用程式來管理代理程式。管理代理程式前，請先執行以下作業：
-
使用 imqbrokerd 公用程式指令啟動代理程式。代理程式執行後，才能使用其他指令行公用程式。
-
決定是要設定 Message QueueTM 管理使用者，或是使用預設帳號。您必須指定使用者名稱和密碼，才能使用管理指令。
當您安裝 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 子指令更新下列代理程式特性：
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) 和基本傳輸協定相關。
表 5–1 Message Queue 連線服務|
服務名稱 |
服務類型 | |
|---|---|---|
|
NORMAL | ||
|
NORMAL | ||
|
NORMAL | ||
|
NORMAL | ||
|
ADMIN |
TCP |
|
|
ADMIN |
TLS (SSL 型安全性) |
您可以使用 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 中所列出的一個或多個服務特性的值。
表 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 選項指定要顯示的度量類型：
-
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
imqcmd rollback txn -n transactionID
如需更多資訊，請參閱表 14–2 中的 imq.transaction.autorollback 特性。
還可配置代理程式，以便在啟動代理程式時自動回復處於 PREPARED 狀態的作業事件。
- © 2010, Oracle Corporation and/or its affiliates