使用 Agent Builder

本節描述如何使用 Agent Builder，包括您可以使用 Agent Builder 之前必須完成的作業。本節還闡述了您在產生資源類型程式碼後可以利用 Agent Builder 的方法。

本章討論下列主題︰

• 分析應用程式

• 安裝與配置 Agent Builder

• Agent Builder 螢幕

• 啟動 Agent Builder

• 導覽 Agent Builder

• 使用 [建立] 畫面

• 使用 [配置] 畫面

• 使用基於 Agent Builder Korn Shell 的變數 $hostnames

• 特性變數

• 如何複製現有的資源類型

• 編輯產生的來源代碼

• 如何使用 Agent Builder 的指令行版本

分析應用程式

在使用 Agent Builder 之前，您必須決定您的應用程式是否符合可使之高度可用或可延伸的條件。Agent Builder 無法執行這個僅基於應用程式執行時間特性的分析。分析應用程式的適當性提供有關此主題的詳細資訊。

雖然在大多數情況下，Agent Builder 至少會提供一個部分解決方案，但它不可能總是能夠建立應用程式的完整資源類型。例如，更複雜的應用程式可能需要 Agent Builder 依預設不會產生的其他程式碼，如對其他特性加入驗證檢查的程式碼或調諧 Agent Builder 不接觸的參數之程式碼。在此類情況下，您必須對產生的來源代碼或 RTR 檔案進行變更。Agent Builder 就恰好是為提供此種靈活性而設計的。

Agent Builder 會將註釋置於已產生源代碼中的特定位置上，您可以在這些地方新增自己的特定資源類型程式碼。對源代碼進行變更後，您可以使用 Agent Builder 產生的 makefile 重新編譯源代碼以及重新產生資源類型套裝軟體。

即使您寫入整個資源類型程式碼，而未使用由 Agent Builder 產生的任何程式碼，也可以使用 Agent Builder 提供的 makefile 與結構來建立資源類型的 Solaris 套裝軟體。

安裝與配置 Agent Builder

Agent Builder 不需要特殊安裝。Agent Builder 包含於 SUNWscdev 套裝軟體中，依預設，它作為標準 Sun Cluster 軟體安裝的一部分來安裝。「Sun Cluster 軟體安裝指南 (適用於 Solaris 作業系統)」包含更多資訊。

在使用 Agent Builder 之前，請驗證下列資訊：

• Java 運行時間環境包含於變數 $PATH 中。Agent Builder 依賴於 Java (Java 開發工具 1.3.1 版或更高版本)。如果 Java 未包含於 $PATH 中，scdsbuilder 則會傳回並顯示一則錯誤訊息。

• 您已安裝了 Solaris 8 或更高版本的開發者系統支援軟體群組。

• cc 編譯器包含於變數 $PATH 中。Agent Builder 使用變數 $PATH 中的第一個 cc 事件，識別用來產生資源類型之 C 二進位碼的編譯器。如果 cc 未包含於 $PATH 中，Agent Builder 將停用產生 C 程式碼的選項。請參閱使用 [建立] 畫面。

除了標準 cc 編譯程式，您可以將其他編譯程式與 Agent Builder 搭配使用。若要使用其他編譯器，請在 $PATH 中建立一個從 cc 至其他編譯器 (如 gcc) 的符號連結。或者，將 makefile 中的編譯器規格 (目前為 CC=cc) 變更為其他編譯器的完整路徑。例如，在 Agent Builder 產生的 makefile 中，將 CC=cc 變更為 CC=路徑名稱/gcc。在這種情況下，您無法直接運行 Agent Builder，而是必須使用 make 與 make pkg 指令來產生資料服務程式碼與套裝軟體。

Agent Builder 螢幕

Agent Builder 是含有兩個步驟的精靈，每個步驟對應一個螢幕。Agent Builder 將提供下列兩個螢幕，指導您完成建立新資源類型的程序。

1. 建立。在此螢幕上，您要提供關於要建立的資源類型之基本資訊，例如其名稱以及所產生檔案的工作目錄。該工作目錄是您建立和配置資源類型範本的位置。您也要識別要建立的資源種類 (可延伸或防故障備用)、基本應用程式是否為網路支援應用程式 (即是否使用網路與其用戶端進行通訊)，以及要產生的程式碼類型 (C、Korn shell [ksh] 或 GDS)。如需關於 GDS 的資訊，請參閱第 10 章, 一般資料服務。您必須提供關於此螢幕的所有資訊並選取 [建立] 以產生相應的輸出。然後，您可以顯示 [配置] 螢幕。

2. 配置。在此螢幕上，您必須指定可以傳送至任何 UNIX® shell 以啟動基本應用程式的完整指令行。此外，您可以提供停止與測試應用程式的指令。如果您不指定這些指令，則產生的輸出將使用訊號來停止應用程式，並提供預設測試機制。請參閱使用 [配置] 畫面中對測試指令的描述。此畫面還可讓您變更這三個指令中每一個的逾時值。

啟動 Agent Builder

如果無法存取 Agent Builder 的圖形化使用者介面版本，您可以透過指令行介面存取 Agent Builder。請參閱如何使用 Agent Builder 的指令行版本。

如果您從現有資源類型的工作目錄啟動 Agent Builder，Agent Builder 會將 [建立] 畫面與 [配置] 畫面初始化為現有資源類型的值。

透過鍵入下列指令來啟動 Agent Builder：

% /usr/cluster/bin/scdsbuilder

將顯示 [建立] 螢幕。

圖 9–1 [建立] 畫面

導覽 Agent Builder

透過執行下列作業，輸入關於 [建立] 和 [配置] 螢幕的資訊︰

• 在欄位中鍵入資訊。

• 瀏覽目錄結構並選取檔案或目錄。

• 選取一組互斥單選按鈕中的一個，例如，按一下[可延伸] 或 [防故障備用]。

• 按一下 [開啟] 或 [關閉] 方塊。例如，按一下 [網路支援] 將基本應用程式識別為網路支援的應用程式，而保留此方塊為空白識別非網路支援的應用程式。

使用每個螢幕底部的選項可讓您完成作業、移至下一個螢幕或上一個螢幕，或結束 Agent Builder。Agent Builder 透過適當地反白顯示或灰色顯示這些選項來突出顯示。

例如，當您填入了 [建立] 螢幕上的欄位並核取了所需的選項後，請按一下螢幕底部的 [建立]。由於不存在上一個螢幕，並且您在完成此步驟之前無法移至下一步，因此 [上一個] 與 [下一個] 會呈灰色顯示。

Agent Builder 在畫面底部的輸出登錄區域中顯示進度訊息。當 Agent Builder 完成作業時，它將顯示一則成功訊息，或者顯示一則警告，以便查看輸出日誌。將反白顯示 [下一個]，或者如果這是最後一個螢幕，則僅反白顯示 [取消]。

您可以隨時選取 [取消] 以結束 Agent Builder。

瀏覽

特定的 Agent Builder 欄位可讓您鍵入資訊或按一下 [瀏覽]，以瀏覽目錄結構並選取檔案或目錄。

當您按一下 [瀏覽] 時，將會顯示一個與下列螢幕相似的螢幕：

按兩下資料夾以開啟它。當您將游標移至某個檔案時，該檔案的名稱將顯示在 [檔案名稱] 方塊中。當您已找到所需的檔案並將游標移至該檔案時，請按一下 [選取]。

如果您要瀏覽某個目錄，請將游標移至所需的目錄並按一下 [開啟]。如果沒有子目錄，Agent Builder 將關閉瀏覽視窗，並將游標所移至的目錄之名稱置於正確的欄位中。如果該目錄具有子目錄，請按一下 [關閉] 以關閉瀏覽視窗，並重新顯示上一個螢幕。Agent Builder 會將游標所移至的目錄之名稱置於正確的欄位中。

畫面右上角的圖示將執行以下作業：

功能表

Agent Builder 提供 [檔案] 和 [編輯] 下拉式功能表。

[檔案] 功能表

[檔案] 功能表包含兩個選項︰

• 載入資源類型。載入現有資源類型。Agent Builder 提供一個瀏覽畫面，從該畫面您可以選取現有資源類型的工作目錄。如果您啟動 Agent Builder 的目錄中存在資源類型，Agent Builder 將會自動載入該資源類型。[載入資源類型] 可讓您從任何目錄啟動 Agent Builder，並選取現有資源類型，作為建立新資源類型的範本。請參閱如何複製現有的資源類型。

• 結束。結束 Agent Builder。您也可以透過按一下 [建立] 或 [配置] 螢幕上的 [取消] 來結束。

[編輯] 功能表

[編輯] 功能表包含下列選項︰

• 清除輸出日誌。從輸出日誌中清除資訊。每當您選取 [建立] 畫面或 [配置] 畫面時，Agent Builder 均會將狀況訊息附加至輸出登錄。如果您正在進行反覆程序 (該程序可用於對來源代碼進行變更並在 Agent Builder 中重新產生輸出) 並要分離狀況訊息，您可以在每次使用日誌檔前儲存與清除日誌檔。

• 儲存日誌檔。將日誌輸出儲存至檔案。Agent Builder 提供一個可讓您選擇目錄與指定檔案名稱的瀏覽螢幕。

使用 [建立] 畫面

[建立] 畫面

建立資源類型的第一步是填寫 [建立] 畫面，此畫面在您啟動 Agent Builder 時顯示。下圖將說明您在欄位中輸入資訊之後的 [建立] 畫面。

圖 9–2 [建立] 畫面

[建立] 畫面包含以下欄位、單選按鈕以及核取方塊：

• 供應商名稱。用於識別資源類型供應商的名稱。您通常要指定供應商的證券代號，但可唯一識別供應商的任何名稱均有效。僅使用字母數字字元。

• 應用程式名稱。資源類型的名稱。僅使用字母數字字元。

  ---

  注意 –

  供應商名稱與應用程式名稱共同構成了資源類型的完整名稱。完整名稱不得超出 9 個字元。

  ---

• RT 版本。所產生資源類型的版本。[RT 版本] 可辨別屬同一基本資源類型的多個註冊版本或升級版本。

  在 [RT 版本] 欄位中不能使用下列字元︰空白、定位字元、斜線 (/)、反斜線 (\)、星號 (*)、問號 (?)、逗號 (,)、分號 (;)、左方括號 ([) 或右方括號 (])。

• 工作目錄。在該目錄下，Agent Builder 將建立一個目錄結構，以包含為目標資源類型建立的所有檔案。您可以在任何一個工作目錄中僅建立一個資源類型。Agent Builder 會將此欄位初始化為您從中啟動 Agent Builder 的目錄之路徑，但是您可以鍵入其他名稱或使用 [瀏覽] 來尋找其他目錄。

  在工作目錄下，Agent Builder 將會以資源類型名稱建立子目錄。例如，如果 SUNW 是供應商名稱，ftp 是應用程式名稱，則 Agent Builder 會將該子目錄命名為 SUNWftp。

  Agent Builder 會將目標資源類型的所有目錄與檔案都置於該子目錄下。請參閱目錄結構。

• 可延伸或防故障備用。指定目標資源類型將為防故障備用還是可延伸。

• 網路支援。指定基本應用程式是否為網路支援的應用程式，即是否使用網路與其用戶端進行通訊。選取 [網路支援] 核取方塊以指定網路支援，或者不選取該核取方塊以指定非網路支援。

• C、ksh。指定所產生源代碼的語言。雖然這些選項互斥，但是有了 Agent Builder，您仍可以使用 Korn shell 產生的程式碼來建立資源類型，然後重複使用相同資訊來建立 C 產生的程式碼。請參閱如何複製現有的資源類型。

• GDS。指定此服務為通用資料服務。請參閱第 10 章, 一般資料服務，以取得有關建立與配置一般資料服務的資訊。

如果 cc 編譯器不在 $PATH 中，則 Agent Builder 將以灰色顯示 C 單選按鈕，並允許您選取 ksh 單選按鈕。若要指定其他編譯程式，請參閱安裝與配置 Agent Builder結尾處的說明。

當您輸入所需的資訊後，請按一下 [建立]。螢幕底部的 [輸出日誌] 視窗顯示 Agent Builder 執行的動作。您可以從 [編輯] 功能表中選擇 [儲存輸出日誌]，將資訊儲存至輸出日誌。

完成以上作業後，Agent Builder 將顯示一則成功訊息或警告訊息。

• 如果 Agent Builder 無法完成此步驟，請檢查輸出日誌，以取得詳細資訊。

• 如果 Agent Builder 順利完成此步驟，請按 [下一個] 以顯示 [配置] 螢幕，此螢幕可讓您完成產生資源類型的程序。

雖然產生完整的資源類型需要兩個步驟，但您可以在完成第一個步驟 (建立) 之後結束 Agent Builder，而不會遺失您已輸入的資訊或 Agent Builder 已完成的工作。請參閱重複使用完成的工作。

使用 [配置] 畫面

[配置] 畫面

如下圖所示，在 Agent Builder 完成資源類型的建立，並且您選取 [建立] 螢幕上的 [下一個] 之後，將顯示 [配置] 螢幕。您無法在已建立資源類型之前存取 [配置] 畫面。

圖 9–3 [配置] 畫面

[配置] 畫面包含以下欄位：

• Start 指令。可傳送至任何 UNIX shell 以啟動基本應用程式的完整指令行。您必須指定 start 指令。您可以在提供的欄位中鍵入該指令，或使用 [瀏覽] 來尋找包含該指令的檔案，以啟動應用程式。

  完整的指令行必須包含啟動應用程式所必需的所有項目，如主機名稱、連接埠號、配置檔案的路徑等。您還可以指定特性變數，在特性變數中對其進行了描述。如果基於 Korn shell 的應用程式要求在指令行上指定一個主機名稱，您可以使用 Agent Builder 定義的變數 $hostnames。請參閱使用基於 Agent Builder Korn Shell 的變數 $hostnames。

  不要以雙引號 (““) 括住指令。

  ---

  注意 –

  如果基本應用程式具有多個獨立的程序樹，其中每一個都在程序監視設備 (PMF) 的控制下以其自己的標記開始，則您無法指定單一指令。相反，您必須建立一個具有個別指令的文字檔案，以啟動每個程序樹，並在 [Start 指令] 文字欄位中指定該檔案的路徑。請參閱建立具有多個獨立程序樹的資源類型，其中列出了該檔案正常工作需要的某些特殊特性。

  ---

• Stop 指令。可傳送至任何 UNIX shell 以停止基本應用程式的完整指令行。您可以在提供的欄位中鍵入該指令，或使用 [瀏覽] 來尋找包含該指令的檔案，以停止應用程式。您還可以指定特性變數，在特性變數中對其進行了描述。如果基於 Korn shell 的應用程式要求在指令行上指定一個主機名稱，您可以使用 Agent Builder 定義的變數 $hostnames。請參閱使用基於 Agent Builder Korn Shell 的變數 $hostnames。

  此指令是可選用的。如果您不指定 stop 指令，則產生的程式碼將使用訊號 (位於 Stop 方法中) 來停止應用程式，如下所示︰

  • Stop 方法傳送 SIGTERM 以停止應用程式，並等待逾時值之 80% 的時間以結束應用程式。

  • 如果 SIGTERM 訊號失敗，則 Stop 方法將傳送 SIGKILL 以停止應用程式，並等待逾時值之 15% 的時間以結束應用程式。

  • 如果 SIGKILL 失敗，則 Stop 方法也將以失敗結束。剩餘 5% 的逾時值被視為經常性耗用時間。

  ---

  注意 –

  確定在應用程式完全停止之前 stop 指令不會傳回。

  ---

• Probe 指令。可定期運行以檢查應用程式運作狀態並傳回 0 (成功) 至 100 (完全失敗) 之間的適當結束狀態的指令。此指令是可選用的。您可以鍵入該指令的完整路徑，或使用 [瀏覽] 來尋找包含該指令的檔案，以測試應用程式。

  一般您將指定基本應用程式的簡單用戶端。如果您未指定 probe 指令，產生的程式碼會僅連接至資源所使用的通訊埠並僅從該通訊埠斷開連接，如果成功，則會宣告應用程式狀態良好。您還可以指定特性變數，在特性變數中對其進行了描述。如果基於 Korn shell 的應用程式要求您在 probe 指令行上指定一個主機名稱，您可以使用 Agent Builder 定義的變數 $hostnames。請參閱使用基於 Agent Builder Korn Shell 的變數 $hostnames。

• 逾時。每個指令的逾時值 (以秒為單位)。您可以指定一個新值，或接受 Agent Builder 提供的預設值 (對於啟動與停止為 300 秒，對於探測為 30 秒)。

使用基於 Agent Builder Korn Shell 的變數 $hostnames

對於許多應用程式，特別是網路支援的應用程式，應用程式在其上偵聽的主機名稱以及客戶所要求的服務，必須傳送至指令行上的應用程式。在許多情況下，主機名稱是您必須為目標資源類型 (位於 [配置] 螢幕上) 的 start、stop 以及 probe 指令指定的參數。不過，應用程式在其上偵聽的主機名稱是叢集特定名稱。主機名稱是在叢集上運行資源時確定的，當Agent Builder 產生資源類型程式碼時，無法確定主機名稱。

為了解決此問題，Agent Builder 將在指令行上提供您可以為 start 指令、stop 指令以及 probe 指令指定的變數 $hostnames。

僅支援變數 $hostnames 與基於 Korn shell 的服務配合使用。不支援變數 $hostnames 與基於 C 的服務和基於 GDS 的服務配合使用。

請完全按照指定實際主機名稱的方式來指定變數$hostnames，例如：

% /opt/network_aware/echo_server -p 連接埠號 -l $hostnames

在叢集上運行目標資源類型的資源時，將以變數 $hostnames 的值取代為該資源配置的主機名稱 LogicalHostname 或 SharedAddress (在資源的 Network_resources_used 資源特性中)。

如果您使用多個主機名稱配置 Network_resources_used 特性，則變數 $hostnames 將包含所有主機名稱，每個名稱之間以逗號分隔。

特性變數

您可以使用特性變數，從 RGM 框架擷取所選 Sun Cluster 資源、資源類型以及資源群組特性的值。Agent Builder 將掃描特性變數的啟動、測試或停止程序檔，並在 Agent Builder 啟動該程序檔之前用它們的值取代這些變數。

不支援特性變數與基於 Korn shell 的服務配合使用。

特性變數清單

以下清單包含您可以與程序檔配合使用的特性變數。在附錄 A, 標準特性 中對 Sun Cluster 資源、資源類型以及資源群組特性進行了描述。

以下清單包含資源特性變數：

• HOSTNAMES

• RS_CHEAP_PROBE_INTERVAL

• RS_MONITOR_START_TIMEOUT

• RS_MONITOR_STOP_TIMEOUT

• RS_NAME

• RS_NUM_RESTARTS

• RS_RESOURCE_DEPENDENCIES

• RS_RESOURCE_DEPENDENCIES_WEAK

• RS_RETRY_COUNT

• RS_RETRY_INTERVAL

• RS_SCALABLE

• RS_START_TIMEOUT

• RS_STOP_TIMEOUT

• RS_THOROUGH_PROBE_INTERVAL

• SCHA_STATUS

以下清單包含資源類型特性變數：

• RT_API_VERSION

• RT_BASEDIR

• RT_FAILOVER

• RT_INSTALLED_NODES

• RT_NAME

• RT_RT_VERSION

• RT_SINGLE_INSTANCE

以下清單包含資源群組特性變數︰

• RG_DESIRED_PRIMARIES

• RG_GLOBAL_RESOURCES_USED

• RG_IMPLICIT_NETWORK_DEPENDENCIES

• RG_MAXIMUM_PRIMARIES

• RG_NAME

• RG_NODELIST

• RG_NUM_RESTARTS

• RG_PATHPREFIX

• RG_PINGPONG_INTERVAL

• RG_RESOURCE_LIST

特性變數語法

在特性名稱之前加入百分比符號 (%) 以指示特性變數，如以下範例所示。

# /opt/network_aware/echo_server -t %RS_STOP_TIMEOUT -n %RG_NODELIST

考慮到前面的範例，Agent Builder 可能會解譯這些特性變數，並使用下列值啟動 echo_server 程序檔。

# /opt/network_aware/echo_server -t 300 -n phys-node-1,phys-node-2,phys-node-3

Agent Builder 如何取代特性變數

以下清單描述了 Agent Builder 如何解譯特性變數的類型：

• 整數被其實際值取代 (例如，300)。

• 布林值被字串 TRUE 或 FALSE 取代。

• 字串被實際字串取代 (例如，phys-node-1)。

• 字串清單被清單中的所有成員取代，每個成員以逗號分隔 (例如，phys-node-1,phys-node-2,phys-node-3)。

• 整數清單被清單中的所有成員取代，每個成員以逗號分隔 (例如，1,2,3)。

• 列舉類型被其字串形式的值取代。

重複使用完成的工作

Agent Builder 可讓您以下列方法重複使用已完成的工作︰

• 您可以複製使用 Agent Builder 建立的現有資源類型。

• 您可以編輯 Agent Builder 產生的源代碼，然後重新編譯該代碼以建立一個新的套裝軟體。

如何複製現有的資源類型

依照此程序複製 Agent Builder 產生的現有資源類型。

1. 使用下列方法之一，將現有的資源類型載入 Agent Builder：

   • 從現有資源類型 (使用 Agent Builder 建立) 的工作目錄 (包含 rtconfig 檔案) 啟動 Agent Builder。Agent Builder 會在 [建立] 和 [配置] 螢幕中載入該資源類型的值。

   • 使用 [檔案] 下拉式功能表中的 [載入資源類型] 選項。

2. 變更 [建立] 畫面上的工作目錄。

   您必須使用 [瀏覽] 來選取目錄。鍵入新的目錄名稱還不夠。當您選取目錄後，Agent Builder 會重新啟動 [建立] 按鈕。

3. 進行變更。

   您可以使用此程序來變更為資源類型產生的程式碼之類型。例如，如果您初始建立 Korn shell 版本的資源類型，但稍後發現需要 C 版本，您可以載入現有的 Korn shell 資源類型，將輸出語言變更為 C，然後使 Agent Builder 建立 C 版本的資源類型。

4. 建立複製的資源類型。

   按一下 [建立] 以建立資源類型。按一下 [下一個] 以顯示 [配置] 螢幕。按一下 [配置] 以配置資源類型，然後按一下 [取消] 完成。

編輯產生的來源代碼

若要使建立資源類型的程序保持簡單，Agent Builder 將會限制輸入的數目，此數目會必要地限制所產生資源類型的範圍。因此，若要增加更複雜的功能 (如其他特性的驗證檢查) 或調諧 Agent Builder 不接觸的參數，您需要修改產生的來源代碼或 RTR 檔案。

來源檔位於 install_directory /rt_name/src 目錄中。Agent Builder 將在可新增程式碼的位置內嵌入來源代碼的註釋。這些註釋的格式為 (對於 C 程式碼)：

/* User added code -- BEGIN vvvvvvvvvvvvvvv */
/* User added code -- END   ^^^^^^^^^^^^^^^ */

除了井字號(#) 指示註釋的開始之外，這些註釋在 Korn shell 來源代碼方面是完全相同的。

例如，rt_name.h 宣告不同程式使用的所有公用程式常式。在宣告清單結尾處是可讓您宣告其他常式 (您可能已將其加入至某程式碼) 的註釋。

Agent Builder 也會在 install_directory/rt_name/src 目錄中產生具有適當目標的 makefile。使用 make 指令重新編譯源代碼，並使用 make pkg 指令重新產生資源類型套裝軟體。

RTR 檔案位於 install_directory/ rt_name/etc 目錄中。您可以使用標準文字編輯器編輯 RTR 檔案。請參閱設定資源特性和資源類型特性以取得關於 RTR 檔案的更多資訊，參閱附錄 A, 標準特性 以取得關於特性的資訊。

如何使用 Agent Builder 的指令行版本

Agent Builder 的指令行版本與圖形化使用者介面具有相同的基本程序。不過，與在圖形化使用者介面中輸入資訊不同，您要將參數傳送至指令 scdscreate 和 scdsconfig。請參閱 scdscreate(1HA) 和 scdsconfig(1HA) 線上說明手冊。

依照以下步驟使用 Agent Builder 的指令行版本：

1. 使用 scdscreate 建立 Sun Cluster 資源類型範本，以使應用程式高度可用或可延伸。

2. 使用 scdsconfig 配置您使用 scdscreate 建立的資源類型範本。

   您可以指定特性變數。特性變數中描述了特性變數。

3. 將目錄變更為工作目錄中的 pkg 子目錄。

4. 使用 pkgadd 指令安裝您透過 scdscreate 建立的套裝軟體。

5. 如果需要，請編輯產生的來源代碼。

6. 執行啟動程序檔。