fteCreateCDAgent (建立 Connect:Direct 橋接器代理程式)

fteCreateCDAgent 指令會建立 Managed File Transfer Agent 及其相關聯的配置，以與 Connect:Direct® 橋接器搭配使用。

重要事項: [AIX、Linux、Windows]在 IBM® MQ for AIX®, Linux®, and Windows上，只有身為 IBM MQ 管理者 (及 mqm 群組成員) 的使用者才能執行此指令。 如果您嘗試以非 IBM MQ 管理者的使用者身分執行此指令，則會收到錯誤訊息BFGCL0502E: You are not authorized to perform the requested operation.指令將不會執行。
[z/OS]在 z/OS® 系統上，使用者必須滿足 (至少) 下列其中一個條件，才能執行指令:
  • 是 mqm 群組的成員（如果 mqm 群組已定義在系統上）。
  • 是 BFG_GROUP_NAME 環境變數所指名之群組的成員（如果已指名群組的話）。
  • 指令執行時，BFG_GROUP_NAME 環境變數中未設定任何值。

用途

使用 fteCreateCDAgent 指令來建立 Connect:Direct 橋接器代理程式。 這種類型的代理程式專用於與 Connect:Direct 節點來回傳送檔案。 如需相關資訊，請參閱 Connect:Direct 橋接器。 如需 Connect:Direct 橋接器所支援作業系統版本的詳細資料，請參閱 IBM MQ系統需求網頁。

此指令提供一些 MQSC 指令，必須針對代理程式佇列管理程式執行這些指令，才能建立下列代理程式佇列：
  • SYSTEM.FTE.AUTHADM1.agent_name
  • SYSTEM.FTE.AUTHAGT1.agent_name
  • SYSTEM.FTE.AUTHMON1.agent_name
  • SYSTEM.FTE.AUTHOPS1.agent_name
  • SYSTEM.FTE.AUTHSCH1.agent_name
  • SYSTEM.FTE.AUTHTRN1.agent_name
  • SYSTEM.FTE.COMMAND.agent_name
  • SYSTEM.FTE.DATA.agent_name
  • SYSTEM.FTE.EVENT.agent_name
  • SYSTEM.FTE.REPLY.agent_name
  • SYSTEM.FTE.STATE.agent_name

這些佇列是內部系統佇列，您不得從中修改、刪除或讀取訊息，除非您刪除代理程式。 下列位置的檔案也提供了要執行的 MQSC 指令：MQ_DATA_PATH\mqft\config\coordination_qmgr_name\agents\agent_name\agent_name_create.mqsc。

如果您稍後想要刪除此代理程式，這個指令也提供您 MQSC 指令，您必須執行它們，才能清除及刪除屬於此代理程式的佇列。 MQSC 指令位於下列位置的檔案中: MQ_DATA_PATH\mqft\config\coordination_qmgr_name\agents\agent_name\agent_name_delete.mqsc。

Managed File Transfer 提供進階代理程式內容，可協助您配置代理程式。 這些內容在 MFT agent.properties 檔案中有說明。

fteCreateCDAgent 指令會在代理程式內容目錄中建立兩個 XML 檔案。 ConnectDirectNodeProperties.xml， 用於定義傳送中遠端節點的相關資訊，以及 ConnectDirectProcessDefinitions.xml，用於指定由傳送啟動哪些使用者定義的 Connect:Direct 處理程序。

若要定義 Connect:Direct 橋接器代理程式用來連接至 Connect:Direct 節點的使用者名稱及密碼，您必須手動建立 ConnectDirectCredentials.xml 檔案。 範例 XML 檔案位於 MQ_INSTALLATION_PATH/mqft/samples/credentials/ 中。 如需相關資訊和範例，請參閱 Connect:Direct 認證檔案格式。

重要事項：

在 AIX 及 Linux Managed File Transfer 指令上，使用 Socket 檔案與在相同主機上執行的代理程式處理程序進行通訊。

這些 Socket 檔案建立在代理程式的日誌目錄中，並在代理程式停止時刪除。 在 IBM MQ Managed File Transfer 安裝中，此 Socket 檔案是以下列檔案路徑建立: <MQ_DATA_PATH>/mqft/logs/<COORDINATION_QM_NAME>/agents/<AGENT_NAME>/logs/<AGENT_NAME>@<AGENT_QM_NAME> ，其中 MQ_DATA_PATH 依預設為 /var/mqm 。

若為可重新配送的代理程式，會在下列目錄下建立此 Socket 檔案: <RE_DISTRIBUTABLE_DIRECTORY>/mqft/logs/<COORDINATION_QM_NAME>/agents/<AGENT_NAME>/logs/<AGENT_NAME>@<AGENT_QM_NAME>。

例如，如果代理程式名稱為 SRCAGENT，代理程式佇列管理程式名稱為 SRCAGENTQM，協調佇列管理程式名稱為 COORDQM，且可重新配送的代理程式從目錄 /home/myuser/mqmft-redist執行，則此 Socket 檔案的完整路徑為: /home/myuser/mqmft-redist/mqft/logs/COORDQM/agents/SRCAGENT/logs/SRCAGENT@SRCAGENTQM

其檔案路徑長度總計為 85 個字元。

Socket 檔案的這些作業系統所容許的路徑長度上限為 107 個字元。 因此，在建立代理程式時，請小心確定 Socket 檔案路徑不超過 107 個字元。 這對於可重新配送的代理程式尤其重要，代理程式的日誌目錄可以位於任意目錄位置。 如需設定配置目錄的詳細資料，請參閱 fteCreateEnvironment 指令。

如果您啟動代理程式，或執行連接至代理程式的其他指令，且您的路徑長度超過 107 個字元，則會收到下列訊息:
BFGNV0159E: 嘗試連結至具有 FFDC 的 Socket 檔案失敗

特殊字元

如果使用的參數值包含特殊字元，請格外小心，以免指令 Shell 解譯字元的方式不符合預期。 例如，包含空格、引號 (單或雙)、反斜線或正斜線字元等字元的完整檔案路徑及名稱，可能由指令 Shell 解譯，而不是直接傳遞至指令本身。 若要避免指令 Shell 解譯字元，請以雙引號或單引號括住整個參數，或使用指令 Shell 的 ESC 序列來跳出特殊字元。 在 Windows 上指定檔案路徑時，請確保將分隔字元反斜線 (\) 輸入為雙反斜線 (\\) ，即跳出反斜線 (\)。  或者，您可以使用單一正斜線 (/) 字元作為分隔字元。"

fteCreateCDAgent

Read syntax diagramSkip visual syntax diagramfteCreateCDAgent-agentName agent_name-agentQMgr agent_qmgr_name-cdNodecd_node_name -agentQMgrHostagent_qmgr_host-agentQMgrPortagent_qmgr_port-agentQMgrChannelagent_qmgr_channel-agentDescagent_description-ac-authorityChecking-pconfiguration_options-f-cdNodeHostcd_node_host-cdNodePortcd_node_port-cdTmpDircd_tmp_dir-sservice_name-suuser_name-sppassword-sjoptions-sloptions-n-mquseriduser_id-nolpw-mqpasswordpassword-nolpw-credentialsFilefile_path-useridusername

參數

-agentName 代理程式名稱
必要項目。 要建立的代理程式的名稱。 代理程式名稱對其協調佇列管理程式必須是唯一的。
如需命名代理程式的相關資訊，請參閱 物件命名慣例。
-agentQMgr 代理程式佇列管理程式名稱
必要項目。 代理程式佇列管理程式的名稱。
-cdNode cd_node_name
必要項目。 用來將訊息從此代理程式傳送至目的地 Connect:Direct 節點的 Connect:Direct 節點名稱。 此參數的值用於記載，而不是指定要連接至節點的 Connect:Direct 橋接器代理程式。 -cdNodeHost 和 -cdNodePort 的值指定屬於 Connect:Direct 橋接器的 Connect:Direct 節點。
-agentQMgr主機 agent_qmgr_host
選用項目。 代理程式佇列管理程式的主機名稱或 IP 位址。
-agentQMgr埠 agent_qmgr_port
選用項目。 用戶端連接代理程式佇列管理程式所使用的埠號。
-agentQMgr通道 agent_qmgr_channel
選用項目。 用於連接至代理程式佇列管理程式的通道名稱。
-agentDesc 代理程式說明
選用項目。 代理程式的說明，顯示在 IBM MQ Explorer中。
-ac 或 -authorityChecking
選用項目。 此參數會啟用權限檢查。 如果您指定此參數，代理程式會檢查是否已授權提交要求的使用者執行所要求的動作。 如需相關資訊，請參閱 限制 MFT 代理程式動作的使用者權限。
-p configuration_options
選用項目。 此參數會決定用於建立代理程式的配置選項集。 依照慣例，會使用非預設協調佇列管理程式的名稱作為此參數的輸入。 然後， fteCreateCDAgent 指令會使用與此非預設協調佇列管理程式相關聯的內容檔集。

只有在您想要使用不同於預設值的配置選項時，才需指定選用的 -p 參數。 如果未指定此參數，則會使用一組以預設協調佇列管理程式為基礎的配置選項。

-f
選用項目。 強制指令改寫不符合的現有參數。 指定此參數，並不會強制取代現有的 Windows 服務代理程式。
-cdNode主機 cd_node_host_name
選用項目。 由 -cdNode 參數指定的 Connect:Direct 節點所在系統的主機名稱或 IP 位址。 如果您沒有指定 -cdNodeHost 參數，則會使用本端系統主機名稱或 IP 位址的預設值。
在大部分情況下， Connect:Direct 節點與 Connect:Direct 橋接器代理程式位於相同的系統上。 在這些情況下，此內容的預設值（即本端系統的 IP 位址）是正確的。 如果系統具有多個 IP 位址，或者 Connect:Direct 節點與 Connect:Direct 橋接器代理程式位於不同的系統上，且其系統共用一個檔案系統，請使用此內容為 Connect:Direct 節點指定正確的主機名稱。
-cdNode埠 cd_node_port_name
選用項目。 用戶端應用程式用來與 -cdNode 參數所指定節點進行通訊之 Connect:Direct 節點的埠號。 在 Connect:Direct 產品說明文件中，此埠稱為 API 埠。 如果您沒有指定 -cdNodePort 參數，則會假設預設埠號為 1363。
-cdTmp目錄 cd_tmp_directory
選用項目。 在檔案傳送至目的地 Connect:Direct 節點之前，此代理程式用來暫時儲存檔案的目錄。 此參數會指定暫時儲存檔案的目錄之完整路徑。 比方說，例如將 cdTmpDir 設定為 /tmp，則會將檔案暫時放置在 /tmp 目錄中。 如果您沒有指定 -cdTmpDir 參數，則會將檔案暫時儲存在名為 cdbridge-agent_name 的目錄中。 此預設目錄建立於 java.io.tmpdir 內容值所定義的位置中。

Connect:Direct 橋接器代理程式及 Connect:Direct 橋接器節點必須能夠使用相同的路徑名稱來存取此參數指定的目錄。 在規劃安裝 Connect:Direct 橋接器時，請考量此項。 可能的話，請在屬於 Connect:Direct 橋接器的 Connect:Direct 節點所在的系統上建立代理程式。 如果您的代理程式及節點在不同的系統上，則此目錄必須在共用檔案系統上，並可使用相同路徑名稱從這兩個系統進行存取。 如需受支援配置的相關資訊，請參閱 Connect:Direct 橋接器。

附註: 如果您執行 fteCleanAgent 指令，則會刪除此目錄中的所有檔案。
[Windows]-s service_name
選用（僅限於 Windows）。 指出代理程式以 Windows 服務方式執行，指令必須從 Windows 管理者使用者 ID 執行。 如果未指定 service_name，則此服務會命名為 mqmftAgentAGENTQMGR，其中 AGENT 是代理程式名稱，而 QMGR 是代理程式佇列管理程式名稱。
[Windows]-su 使用者名稱
選用（僅限於 Windows）。 代理程式以 Windows 服務執行時，此參數會指定執行服務所使用的帳戶名稱。 若要使用 Windows 網域使用者帳戶來執行代理程式，請以 DomainName\UserName格式指定值。 若要使用本端內建網域中的帳戶執行服務，請以 UserName 格式指定值。
[Windows]-sp 密碼
選用（僅限於 Windows）。
[Windows]-sj 選項
選用（僅限於 Windows）。 以 Windows 服務啟動代理程式時，以 -D 或 -X 的格式定義傳遞至 JVM 的選項清單。 這些選項會使用 # 記號或分號 (;) 字元來區隔。 如果您必須內含任何 # 或分號 (;) 字元，請將這些字元放在單引號內。
[Windows]-sl 選項
選用（僅限於 Windows）。 設定 Windows 服務日誌層次。 有效的選項是：error、info、warn、debug。 預設值是 info。 此選項在您發生 Windows 服務問題時會很有幫助。 將它設為 debug，可以在服務日誌檔中提供更詳細資訊。
[Windows]-n
選用（僅限於 Windows）。 指示代理程式以正常程序執行。 此參數與 -s 選項互斥。 如果既不指定 -s 參數，也不指定 -n 參數，則代理程式會配置為正常 Windows 處理程序。
-mquserid user_id
選用項目。 指定用來向指令佇列管理程式進行鑑別的使用者 ID。
-mqpassword password
選用項目。 指定用來向協調佇列管理程式進行鑑別的密碼。
當指定 -mqpassword 參數時，您也必須指定 -mquserid 參數。 如果您指定 -mquserid，但未指定 -mqpassword，則系統會提示您提供相關聯的密碼，不會顯示此密碼。

[MQ 9.3.0 Jun 2022][MQ 9.3.0 Jun 2022]從 IBM MQ 9.3 開始，指令預設為使用 MQCSP 鑑別，並將要鑑別的使用者 ID 和密碼傳送至 MQCSP 結構中的佇列管理程式。

[MQ 9.3.0 Jun 2022][MQ 9.3.0 Jun 2022]-nolpw
選用項目。 如果指令所連接的佇列管理程式不支援超過 12 個字元的密碼，請指定此參數。
當指定 -nolpw 參數時，您也必須指定 -mquserid 參數。 如果您指定 -mquserid 及 -nolpw，但未指定 -mqpassword，則系統會提示您提供相關聯的密碼，不會顯示該密碼。
附註: 如果您指定 -nolpw 選項，且密碼長度超過 12 個字元，則指令會失敗，並顯示錯誤訊息 BFGCL0829E。
-credentialsFile 檔案路徑
選用項目。 現有或新認證檔的完整檔案路徑， IBM MQ 鑑別詳細資料會新增至其中。
此指令支援將一組 IBM MQ 鑑別詳細資料新增至具名 Managed File Transfer 認證檔。 當已啟用 IBM MQ 連線鑑別時，請使用這個指令。 如果更新現有的詳細資料，則必須使用 -f 強制參數。
-userid username
選用項目。 用來與認證詳細資料相關聯的使用者 ID。 如果未指定使用者 ID，則認證詳細資料將套用至所有使用者。 您還必須指定 -credentialsFile 參數。

範例

在此範例中，會使用代理程式佇列管理程式 QM_NEPTUNE 來建立新的 Connect:Direct 橋接器代理程式 CD_BRIDGE。 代理程式會使用 Connect:Direct 節點 BRIDGE_NODE ，將檔案傳送至其他 Connect:Direct 節點。 BRIDGE_NODE 節點位於與此代理程式相同的系統上，並且使用預設埠進行用戶端連線。 與 Connect:Direct 來回傳送的檔案暫時儲存在 /tmp/cd-bridge目錄中。

fteCreateCDAgent -agentName CD_BRIDGE -agentQMgr QM_NEPTUNE 
                 -cdNode BRIDGE_NODE -cdTmpDir /tmp/cd-bridge

回覆碼

0
指令已順利完成。
1
指令未順利結束。