test

Sun Cluster 資料服務開發者指南 (適用於 Solaris 作業系統)

第 3 章 資源管理 API 參考

本章列舉並簡要說明組成資源管理 API (RMAPI) 的存取函數和回呼方法。然而，這些函數與方法的決定性參考是 RMAPI 線上援助頁。

本章涵蓋下列主題：

RMAPI 存取方法

API 提供函數以存取資源類型、資源和資源群組特性，以及其他叢集資訊。這些函數同時以 Shell 指令和 C 函數的形式提供，可讓您將控制程式實作為 Shell 程序檔或 C 程式。

RMAPI Shell 指令

Shell 指令用於表示服務 (由叢集的 RGM 控制) 的資源類型回呼方法之 Shell 程序檔實作。您可以使用這些指令完成以下作業︰

備註 –

本小節提供 Shell 指令的簡要說明，1HA 線上手冊提供了 Shell 指令的最可靠參考。每個相同名稱的線上手冊與指令相關聯，除非另有註釋。

RMAPI 資源指令

您可以存取有關資源的資訊或使用這些指令設定資源的 Status 和 Status_msg 特性。

scha_resource_get

存取有關 RGM 控制下的資源或資源類型的資訊。此指令提供與 scha_resource_get() C 函數相同的資訊。如需詳細資訊，請參閱 scha_resource_get(1HA) 線上手冊。

scha_resource_setstatus

設定在 RGM 控制下的資源的 Status 和 Status_msg 特性。資源監視器使用此指令以表示由監視器察覺到的資源狀態。此指令提供與 scha_resource_setstatus() C 函數相同的功能。scha_resource_setstatus(1HA) 線上手冊更詳細地說明了此指令。

備註 –

儘管 scha_resource_setstatus() 對資源監視器特別有用，但任何程式都可以呼叫它。

資源類型指令

scha_resourcetype_get

存取有關使用 RGM 註冊的資源類型的資訊。該指令與 scha_resourcetype_get() C 函數提供的功能性相同。scha_resourcetype_get(1HA) 線上手冊更詳細地說明了此指令。

資源群組指令

您可以使用這些指令存取有關資源群組的資訊或重新啟動資源群組。

scha_resourcegroup_get

存取有關在 RGM 控制下的資源群組的資訊。該指令與 scha_resourcetype_get() C 函數提供的功能性相同。scha_resourcegroup_get(1HA) 線上手冊更詳細地說明了此指令。

scha_control

請求重新啟動在 RGM 控制下的資源群組或將其遷移至其他節點。該指令與 scha_control() C 函數提供的功能性相同。scha_control(1HA) 線上手冊更詳細地說明了此指令。

叢集指令

scha_cluster_get

存取有關叢集的資訊，如叢集名稱、節點名稱、ID、狀態，以及資源群組。此指令提供與 scha_cluster_get() C 函數相同的資訊。scha_cluster_get(1HA) 線上手冊更詳細地說明了此指令。

C 函數

C 函數用於表示服務 (由叢集的 RGM 控制) 的資源類型回呼方法之 C 程式實作中。您可以使用這些函數完成以下作業︰

備註 –

本小節提供 C 函數的簡要說明，但 3HA 線上手冊提供 C 函數的最可靠參考。每個相同名稱的線上手冊與函數相關聯，除非另有註釋。請參閱 scha_calls(3HA) 線上手冊，以取得有關輸出引數和 C 函數回覆碼的資訊。

資源函數

這些函數可存取有關由 RGM 管理的資源的資訊或表示由監視器察覺的資源狀態。

scha_resource_open()、scha_resource_get() 和 scha_resource_close()

這些函數可存取有關由 RGM 管理的資源的資訊。scha_resource_open() 函數初始化對資源的存取並傳回 scha_resource_get() 的一個控點，該函數將存取資源資訊。scha_resource_close() 函數使控點無效，並且釋放為 scha_resource_get() 回覆值配置的記憶體。

在 scha_resource_open() 傳回資源的控點後，資源可透過叢集重新配置或管理動作進行變更。因此，scha_resource_get() 透過控點取得的資訊可能不正確。如果某個資源上發生叢集重新配置或管理動作，RGM 會將 scha_err_seqid 錯誤碼傳回至 scha_resource_get()，以表示有關該資源的資訊可能已變更。此錯誤訊息為非嚴重訊息。函數將成功地傳回。您可以選擇忽略該訊息並接受傳回的資訊。或者，您可以關閉目前的控點，然後開啟新的控點以存取有關資源的資訊。

線上手冊將說明這三個函數。您可以透過任意個別函數 scha_resource_open(3HA)、scha_resource_get(3HA) 或 scha_resource_close(3HA) 存取此線上手冊。

scha_resource_setstatus()

設定在 RGM 控制下的資源的 Status 和 Status_msg 特性。資源的監視器使用此函數來指示資源的狀態。

備註 –

儘管 scha_resource_setstatus() 對資源監視器特別有用，但任何程式都可以呼叫它。

資源類型函數

這些函數可存取有關使用 RGM 註冊的資源類型之資訊。

scha_resourcetype_open()、scha_resourcetype_get() 和 scha_resourcetype_close()

scha_resourcetype_open() 函數初始化對資源的存取並傳回 scha_resourcetype_get() 的一個控點，該函數將存取資源類型資訊。scha_resourcetype_close() 函數使控點無效，並且釋放為 scha_resourcetype_get() 回覆值配置的記憶體。

在 scha_resourcetype_open() 傳回資源類型的控點後，資源類型可透過叢集重新配置或管理動作進行變更。因此，scha_resourcetype_get() 透過控點取得的資訊可能不正確。如果某個資源類型上發生叢集重新配置或管理動作，RGM 會將 scha_err_seqid 錯誤碼傳回至 scha_resourcetype_get()，以表示有關此資源類型的資訊可能已變更。此錯誤訊息為非嚴重訊息。函數將成功地傳回。您可以選擇忽略該訊息並接受傳回的資訊。或者，您可以關閉目前的控點，然後開啟新的控點以存取有關資源類型的資訊。

線上手冊將說明這三個函數。您可以透過任意個別函數 scha_resourcetype_open(3HA)、scha_resourcetype_get(3HA) 或 scha_resourcetype_close(3HA) 存取此線上手冊。

資源群組函數

您可以使用這些函數存取有關資源群組的資訊或重新啟動資源群組。

scha_resourcegroup_open()、scha_resourcegroup_get() 和 scha_resourcegroup_close()

這些函數可存取有關由 RGM 管理的資源群組的資訊。scha_resourcegroup_open() 函數初始化對資源群組的存取，並為 scha_resourcegroup_get () 傳回控點，該函數將存取資源群組資訊。scha_resourcegroup_close() 函數使控點無效，並且釋放為 scha_resourcegroup_get() 回覆值配置的記憶體。

在 scha_resourcegroup_open() 傳回資源群組的控點後，資源群組可透過叢集重新配置或管理動作進行變更。因此，scha_resourcegroup_get() 透過控點取得的資訊可能不正確。如果某個資源群組上發生叢集重新配置或管理動作，RGM 會將 scha_err_seqid 錯誤碼傳回至 scha_resourcegroup_get()，以表示有關資源群組的資訊可能已變更。此錯誤訊息為非嚴重訊息。函數將成功地傳回。您可以選擇忽略該訊息並接受傳回的資訊。或者，您可以關閉目前的控點，然後開啟新的控點以存取有關資源群組的資訊。

線上手冊將說明這三個函數。您可以透過任意個別函數 scha_resourcegroup_open(3HA)、 scha_resourcegroup_get(3HA) 和 scha_resourcegroup_close(3HA) 存取此線上手冊。

scha_control()

請求在 RGM 控制下的資源群組重新啟動或將其遷移至其他節點。此函數在 scha_control(3HA) 線上手冊中有詳細說明。

叢集函數

這些函數可存取或傳回有關叢集的資訊。

scha_cluster_open()、scha_cluster_get() 和 scha_cluster_close()

這些函數可存取有關叢集的資訊，如叢集名稱、節點名稱、ID、狀態，以及資源群組。

在 scha_cluster_open() 傳回叢集的控點後，叢集可透過叢集重新配置或管理動作進行變更。因此，scha_cluster_get() 透過控點取得的資訊可能不正確。如果某個叢集上發生重新配置或管理動作，RGM 會將 scha_err_seqid 錯誤碼傳回至 scha_cluster_get()，以表示有關叢集的資訊可能已變更。此錯誤訊息為非嚴重訊息。函數將成功地傳回。您可以選擇忽略該訊息並接受傳回的資訊。或者，您可以關閉目前的控點，然後開啟新的控點以存取有關叢集的資訊。

線上手冊將說明這三個函數。您可以透過任意個別函數 scha_cluster_open(3HA)、scha_cluster_get(3HA) 和 scha_cluster_close(3HA) 存取此線上手冊。

scha_cluster_getlogfacility()

傳回用做叢集記錄的系統記錄功能的數目。使用傳回的值與 syslog() Solaris 函數將事件和狀態訊息記錄至叢集記錄。scha_cluster_getlogfacility(3HA) 線上手冊更詳細地說明了此函數。

scha_cluster_getnodename()

傳回在其上呼叫函數之叢集節點的名稱。scha_cluster_getnodename(3HA) 線上手冊更詳細地說明了此函數。

公用程式函數

此函數將錯誤碼轉換為錯誤訊息。

scha_strerror()

將由 scha_ 函數之一傳回的錯誤碼轉譯為相應的錯誤訊息。使用此函數與 logger 指令將訊息記錄在 Solaris 系統記錄 (syslog) 中。scha_strerror(3HA) 線上手冊更詳細地說明了此函數。

RMAPI 回呼方法

回呼方法為 API 提供的關鍵元素，用於實作資源類型。如果在叢集成員關係中發生變更 (例如，節點的啟動或當機)，回呼方法可讓 RGM 控制叢集中的資源。

備註 –

由於用戶端程式控制叢集系統中的 HA 服務，因此，RGM 使用超級使用者或相等的角色權限執行回呼方法。安裝與管理這些具有限制性檔案所有權與許可權的方法。尤其為這些方法提供一個具有權限的所有者，例如 bin 或 root，並不使它們成為可寫入的。

本小節說明回呼方法引數和結束碼。在以下種類中說明回呼方法︰

備註 –

本小節提供回呼方法的簡要說明，包括方法在資源上執行的位置和預期的效果。然而，rt_callbacks(1HA) 線上手冊是回呼方法的最可靠參考。

您可以提供給回呼方法的引數

RGM 執行回呼方法，如下所示︰

method -R resource-name -T type-name -G group-name

方法是註冊為 Start、Stop 或其他回呼的程式之路徑名稱。資源類型的回呼方法將在其註冊檔案中宣告。

所有回呼方法引數均作為標幟的值傳送，如下所示︰

配合使用引數與存取函數來擷取有關資源的資訊。

使用附加引數 (包含在其上進行呼叫的資源和資源群組的特性值) 呼叫 Validate 方法。

scha_calls(3HA) 線上手冊包含更多資訊。

回呼方法結束碼

所有回呼方法具有相同的結束碼。定義這些結束碼以指定在資源狀態上的方法呼叫效果。scha_calls(3HA) 線上手冊更詳細地說明了這些結束碼。結束碼的兩個主要類別如下︰

RGM 也會處理回呼方法執行的非正常失敗，例如，逾時與記憶體傾印。

方法實作必須透過使用每個節點上的 syslog() 輸出失敗資訊。寫入 stdout 或 stderr 的輸出不保證將傳送至使用者，儘管其目前顯示在本機節點的主控台上。

控制與初始化回呼方法

主要的控制和初始化回呼方法將啟動與停止資源。其他方法執行資源上的初始化程式碼與終止程式碼。

Start

當包含資源的資源群組在某節點上處於線上狀態時，RGM 將在該叢集節點上執行此方法。這個方法將啟動該節點上的資源。

Start 方法直到其啟動的資源已經啟動並在本機節點上可用時，才可結束。因此，在 Start 方法結束之前，應輪詢資源以確定資源已啟動。此外，您應為此方法設定一個足夠長的逾時值。例如，資料庫常駐程式等特定資源將花費更多的時間用於啟動，因此需要該方法具有更長的逾時值。

RGM 回應 Start 方法故障的方式取決於 Failover_mode 特性的設定。

資源類型註冊 (RTR) 檔案中的 Start_timeout 特性將設定資源的 Start 方法的逾時值。

Stop

當包含資源的資源群組在某節點上處於離線狀態時，RGM 將在該叢集節點上執行此需要的方法。如果資源處於使用中狀態，則該方法將取消啟動資源。

Stop 方法直到其控制的資源已經在本機節點上完全停止所有活動，並已關閉所有檔案描述元時，才可結束。否則，由於 RGM 會假定資源已停止，而實際上其仍然處於使用中狀態，從而導致資料損毀。防止資料損毀最安全的方法是在與資源相關的本機節點上終止所有程序。

在 Start 方法結束之前，應輪詢資源以決定資源已停止。此外，您應為此方法設定一個足夠長的逾時值。例如，資料庫常駐程式等特定資源將花費更多的時間用於停止，因此需要該方法具有更長的逾時值。

RGM 回應 Stop 方法失敗的方式取決於 Failover_mode 特性的設定。請參閱資源特性。

RTR 檔案中的 Stop_timeout 特性將設定資源的 Stop 方法的逾時值。

Init

當資源變為受管理時，RGM 將執行此可選方法以執行資源的一次性初始化。當其資源群組從未管理狀態轉換為管理狀態時，或當在已管理的資源群組中建立資源時，RGM 將執行此方法。會在由 Init_nodes 資源特性識別的節點上呼叫該方法。

Fini

當資源變為未管理時，RGM 將執行此可選方法以清除資源。當其資源群組轉換為未管理狀態時，或當從管理的資源群組中刪除資源時，RGM 將執行此方法。會在由 Init_nodes 資源特性識別的節點上呼叫該方法。

Boot

在資源群組 (包含資源) 已置於 RGM 管理之下後，RGM 將執行此可選方法 (與 Init 相似) 以初始化加入叢集的節點上的資源。RGM 將在由 Init_nodes 資源特性識別的節點上執行此方法。由於啟動或重新啟動，當節點加入或重新加入叢集時，將呼叫 Boot 方法。

備註 –

Init、Fini 或 Boot 方法的失敗將導致 syslog() 函數產生錯誤訊息。然而，由 RGM 管理的資源不會受影響。

管理支援方法

資源上的管理動作包含設定與變更資源特性。Validate 和 Update 回呼方法可讓資源類型實作執行這些管理動作。

Validate

當建立資源並且叢集管理員更新資源特性或其所在的資源群組特性時，RGM 將呼叫此可選方法。在由資源類型的 Init_nodes 特性識別的叢集節點集上呼叫此方法。在套用建立或更新之前呼叫 Validate。任何節點上方法的失敗結束碼將導致建立或更新被取消。

僅當叢集管理員變更資源或資源群組特性時 (而非在 RGM 設定特性或監視器設定 Status 和 Status_msg 資源特性時)，才呼叫 Validate。

Update

RGM 執行此可選方法以通知正在執行的資源特性已變更。在管理動作成功設定資源特性或其群組特性後，RGM 將執行 Update。將在資源線上運作的節點上呼叫該方法。該方法使用 API 存取函數來讀取特性值 (這些特性值可能會影響使用中的資源)，並將依此調節正在執行的資源。

備註 –

Update 方法的失敗將導致 syslog() 函數產生錯誤訊息。然而，由 RGM 管理的資源不會受影響。

網路相關的回呼方法

使用網路位址資源的服務可能會要求以特定的順序 (與網路位址配置相關) 執行啟動或停止步驟。以下可選回呼方法 Prenet_start 和 Postnet_stop 可讓資源類型實作在配置或取消配置相關網路位址前後執行特殊的啟動和關閉動作。

Prenet_start

在配置相同資源群組中的網路位址之前，會呼叫此可選方法以執行特殊的啟動動作。

Postnet_stop

在取消配置相同資源群組中的網路位址之後，會呼叫此可選方法以執行特殊的關閉動作。

監視器控制回呼方法

資源類型實作可選擇性地包含一個用於監視資源效能、報告其狀態，或當資源發生故障時執行動作的程式。Monitor_start、Monitor_stop 和 Monitor_check 方法支援在資源類型實作中實作資源監視器。

Monitor_start

在啟動資源之後，將呼叫這個可選用的方法來啟動資源的監視器。

Monitor_stop

在停止資源之前，將呼叫這個可選用的方法來停止資源的監視器。

Monitor_check

在資源群組遷移至該節點之前，將呼叫此可選方法以存取節點的穩定性。您必須實作 Monitor_check 方法，以便其不會與其他正在執行的方法相衝突。