test

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

第 4 章 資源管理 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() 函式提供的資訊相同。

scha_resource_setstatus

在 RGM 的控制下設定資源的 Status 特性與 Status_msg 特性。資源的監視器將使用此指令來指示其感知到的資源狀態。它與 scha_resource_setstatus() C 函式提供的功能性相同。

注意 –

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

資源類型指令

此指令存取藉由 RGM 註冊之資源類型的資訊。

scha_resourcetype_get

該指令與 scha_resourcetype_get() C 函式提供的功能性相同。

資源群組指令

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

scha_resourcegroup_get

在 RGM 的控制下存取有關資源群組的資訊。該指令與 scha_resourcetype_get() C 函式提供的功能性相同。

scha_control

要求在 RGM 控制下重新啟動資源群組或將其重新配置到其他節點。該指令與 scha_control() C 函式提供的功能性相同。

叢集指令

該指令存取有關叢集的資訊，如節點名稱、節點 ID 與節點狀態、叢集名稱、資源群組等。

scha_cluster_get

該指令與 scha_cluster_get() C 函式提供的資訊相同。

C 函式

C 函式將用於資源類型的回呼方法之 C 程式實作，表示叢集的 RGM 控制的服務。您可以使用這些函式來執行以下作業：

注意 –

儘管本章提供 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(3HA)、scha_resourcegroup_get(3HA) 和 scha_resourcegroup_close(3HA)

這些指令共同存取有關 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_control( 3HA)

要求在 RGM 控制下重新啟動資源群組或將其重新配置到其他節點。

叢集函式

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

scha_cluster_open(3HA)、 scha_cluster_get(3HA)、 scha_cluster_close(3HA)

這些函式將共同存取有關叢集的資訊，如節點名稱、節點 ID 與節點狀態、叢集名稱、資源群組，等等。

透過重新配置或管理動作，叢集可以在 scha_cluster_open() 傳回叢集的控點之後變更，在這種情況下 scha_cluster_get() 透過控點獲取的資訊可能不準確。如果在叢集上發生重新配置或管理動作，RGM 將傳回 scha_err_seqid 錯誤碼至 scha_cluster_get()，以指示有關叢集的資訊可能已變更。這是一種不嚴重的錯誤訊息；函式可以成功傳回。您可以選擇忽略訊息並接受傳回的資訊，或者可以關閉目前的控點並開啟新控點，以存取有關叢集的資訊。

scha_cluster_getlogfacility(3HA)

傳回目前作為叢集日誌使用的系統日誌工具之編號。使用傳回值與 Solaris syslog() 函式，將事件與狀況訊息記錄到叢集日誌中。

scha_cluster_getnodename(3HA)

傳回在其上呼叫函式之叢集節點的名稱。

公用程式函式

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

scha_strerror( 3HA)

將錯誤碼 (由 scha_ 函式之一傳回) 轉換為相應的錯誤訊息。使用該函式與 logger 將訊息記錄到系統日誌 (syslog) 中。

RMAPI 回呼方法

回呼方法是由 API 提供用於實現資源類型的關鍵元素。如果叢集成員資格中發生變更 (如節點開機或當機)，則回呼方法啟用 RGM 來控制叢集中的資源。

注意 –

因為用戶端程式控制叢集系統上的 HA 服務，所以回呼方法將由具有根許可權的 RGM 來執行。安裝與管理這些具有限制性檔案所有權與許可權的方法。具體來說，給予它們一個具有特權的所有者，如 bin 或 root，且使它們不可寫入。

本節說明回呼方法引數以及退出碼與退出清單，並說明以下種類的回呼方法：

注意 –

儘管本節提供回呼方法的簡要說明，其中包含在其上呼叫方法的點以及資源上預期發生的效果，但 rt_callbacks(1HA) 線上援助頁仍將是回呼方法的決定性參考。

方法引數

RGM 將呼叫回呼方法，如下所示：


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

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

所有回呼方法引數都將作為標定值傳送，其中 -R 指示資源實例的名稱、-T 指示資源的類型，而 -G 指示將資源配置於其中的群組。配合使用引數與存取函式來擷取有關資源的資訊。

使用其他引數 (資源與在其上呼叫資源的資源群組之特性值) 呼叫 Validate 方法。

請參閱 scha_calls(3HA)，以取得詳細資訊。

退出碼

所有回呼方法均定義了相同的退出碼，以指定呼叫該方法對資源狀態產生的效果。scha_calls(3HA) 線上援助頁將說明所有這些退出碼。這些退出碼為：

RGM 也將處理回呼方法執行的非正常故障，如逾時與核心傾印。

方法實作必須使用每個節點上的 syslog 輸出故障資訊。不能保證寫入 stdout 或 stderr 的輸出發送至使用者 (儘管輸出目前顯示在本機節點的主控台上)。

控制與初始化回呼方法

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

Start

當包含資源的資源群組在某個叢集節點上線運作時，將在該節點上呼叫此必需方法。這個方法將啟動該節點上的資源。

Start 方法啟動的資源已啟動並在本機節點上可用時，該方法才應結束。因此，在 Start 方法結束之前，應輪詢資源以確定資源已啟動。此外，您應為此方法設定足夠長的逾時值。例如，某些資源 (如資料庫常駐程式) 的啟動時間很長，因此需要該方法具有較長的逾時值。

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

資源類型註冊檔案中的 START_TIMEOUT 特性設定資源的 Start 方法之逾時值。

Stop

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

Stop 方法應該在其控制的資源已完全停止了在本機節點上的所有活動並已關閉了所有檔案描述元後才結束。否則，由於 RGM 假定資源已停止，而實際上資源仍在作用中，可能導致資料毀壞。避免資料毀壞的最安全方法是終止與資源相關的本機節點上的所有程序。

在 Start 方法結束之前，應輪詢資源以決定資源已停止。此外，您應為此方法設定足夠長的逾時值。例如，某些資源 (如資料庫常駐程式) 的停止時間很長，因此需要該方法具有較長的逾時值。

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

資源類型註冊檔案中的 STOP_TIMEOUT 特性設定資源的 Stop 方法之逾時值。

Init

當資源處於受管理狀態時 (即資源所在的資源群組從未受管理狀態切換至受管理狀態時；或在已經受管理的資源群組中建立資源時)，將呼叫此選用方法，以執行資源的一次性初始化。在 Init_nodes 資源特性決定的節點上呼叫該方法。

Fini

當資源成為不受管理狀態時，當資源所在的資源群組切換到未受管理狀態時，或當從受管理資源群組中刪除資源時，將呼叫此選擇性方法，以執行清除資源作業。在 Init_nodes 資源特性決定的節點上呼叫該方法。

Boot

將呼叫這個與 Init 相似的方法以初始化節點上的資源，這些節點在包含資源的資源群組已置於 RGM 的管理之下後加入叢集。在 Init_nodes 資源特性決定的節點上呼叫該方法。當節點由於啟動或重新啟動而連結或重新連結叢集時，將呼叫 Boot 方法。

注意 –

Init、Fini 或 Boot 方法的失敗將導致 syslog() 函式產生一條錯誤訊息，但不會另外影響資源的 RGM 管理。

管理支援方法

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

Validate

當建立資源和管理動作更新資源或其所在資源群組的特性時，將呼叫此選擇性方法。在資源類型的 Init_nodes 特性指示的叢集節點集上呼叫該方法。在套用建立或更新之前呼叫 Validate，而任意節點上的方法之故障退出碼都會導致取消建立或更新。

僅當透過管理動作變更資源或資源群組特性時，才會呼叫 Validate，而在 RGM 設定特性或監視器設定資源特性 Status 與 Status_msg 時，不呼叫該方法。

Update

呼叫這個可選用的方法，以通知正在執行的資源特性已經變更。在管理動作成功地設定了資源或資源所在群組的特性之後，將呼叫 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 方法必須被實施，以便該方法不與目前正在執行的其他方法衝突。