この章では、Resource Management API (RMAPI) を構成するアクセス関数やコールバックメソッドについてリストし、簡単に説明します。詳細については、RMAPI のそれぞれのマニュアルページを参照してください。
この章の内容は次のとおりです。
「RMAPI アクセスメソッド」 – シェルスクリプトコマンドと C 関数
「RMAPI コールバックメソッド」 – rt_callbacks(1HA) のマニュアルページに説明されている内容
RMAPI は、リソースタイプ、リソース、リソースグループのプロパティー、およびそのほかのクラスタ情報にアクセスするための関数を提供します。これらの関数はシェルコマンドと C 関数の両方の形で提供されるため、開発者はシェルスクリプトまたは C プログラムのどちらでも制御プログラムを実装できます。
シェルコマンドは、クラスタの RGM によって制御されるサービスを表すリソースタイプのコールバックメソッドを、シェルスクリプトで実装するときに使用します。
これらのコマンドを使用すると、次の作業を行えます。
リソースタイプ、リソース、リソースグループ、クラスタについての情報にアクセスする。
モニターと併用し、リソースの Status プロパティーと Status_msg プロパティーを設定する。
リソースグループの再起動または再配置を要求する。
この節では、シェルコマンドについて簡単に説明します。詳細については、各コマンドの (1HA) マニュアルページを参照してください。特に注記しないかぎり、各コマンドと関連付けられた同じ名前のマニュアルページがあります。
以下のコマンドを使用すると、リソースについての情報にアクセスしたり、リソースの Status プロパティーや Status_msg プロパティーを設定できます。
RGM の制御下のリソースまたはリソースタイプに関する情報にアクセスできます。このコマンドは、C 関数 scha_resource_get() と同じ情報を提供します。詳細については、scha_resource_get(1HA) のマニュアルページを参照してください。
RGM の制御下のリソースの Status および Status_msg プロパティーを設定します。このコマンドはリソースのモニターによって使用され、モニターから見たリソースの状態を示します。このコマンドは、C 関数 scha_resource_setstatus() と同じ機能を提供します。このコマンドの詳細については、scha_resource_setstatus(1HA) のマニュアルページを参照してください。
scha_resource_setstatus() はリソースモニター専用の関数ですが、任意のプログラムから呼び出すことができます。
RGM に登録されているリソースタイプについての情報にアクセスします。このコマンドは、C 関数 scha_resourcegroup_get() と同じ機能を提供します。このコマンドの詳細については、scha_resourcetype_get(1HA) のマニュアルページを参照してください。
以下のコマンドを使用すると、リソースグループについての情報にアクセスしたり、リソースグループを再起動できます。
RGM の制御下のリソースグループに関する情報にアクセスできます。このコマンドは、C 関数 scha_resourcegroup_get() と同じ機能を提供します。このコマンドの詳細については、scha_resourcegroup_get(1HA) のマニュアルページを参照してください。
RGM の制御下のリソースグループの再起動、または別のノードまたはゾーンへの再配置を要求します。このコマンドは、C 関数 scha_control() および scha_control_zone() と同じ機能を提供します。このコマンドの詳細については、scha_control(1HA) のマニュアルページを参照してください。
クラスタについての情報 (クラスタ名、ノードまたはゾーン名、ID、状態、およびリソースグループ) にアクセスします。このコマンドは、C 関数 scha_cluster_get() と同じ情報を提供します。このコマンドの詳細については、scha_cluster_get(1HA) のマニュアルページを参照してください。
C 関数は、クラスタの RGM によって制御されるサービスを表すリソースタイプのコールバックメソッドを、C プログラムで実装するときに使用します。
これらの関数を使用すると、次の作業を行えます。
リソースタイプ、リソース、リソースグループ、クラスタについての情報にアクセスする。
リソースの Status および Status_msg プロパティーを設定する。
リソースグループの再起動または再配置を要求する。
エラーコードを適切なエラーメッセージに変換する。
この節では、C 関数について簡単に説明します。C 関数の詳細については、各関数の (3HA) マニュアルページを参照してください。特に注記しないかぎり、各関数と関連付けられた同じ名前のマニュアルページがあります。C 関数の出力引数および戻りコードについては、scha_calls(3HA) のマニュアルページを参照してください。
以下の関数は、RGM に管理されているリソースについての情報にアクセスしたり、モニターから見たリソースの状態を示します。
これらの関数は、RGM によって管理されるリソースに関する情報にアクセスします。scha_resource_open() 関数は、リソースへのアクセスを初期化し、scha_resource_get のハンドルを戻します。scha_resource_get 関数は、リソースの情報にアクセスします。scha_resource_close() 関数は、ハンドルを無効にし、scha_resource_get の戻り値に割り当てられているメモリーを解放します。
scha_resource_open() 関数がリソースのハンドルを戻したあとに、クラスタの再構成や管理アクションによって、リソースが変更されることがあります。その結果、scha_resource_get() 関数がハンドルを通じて獲得した情報は正しくない可能性があります。リソース上でクラスタの再構成や管理アクションが行われた場合、RGM は scha_err_seqid エラーコードを scha_resource_get() 関数に戻し、リソースに関する情報が変更された可能性があることを示します。このエラーメッセージは致命的ではありません。関数は正常に終了します。メッセージを無視し、戻された情報を受け入れることを選択できます。または、現在のハンドルを閉じて新しいハンドルを開き、リソースに関する情報にアクセスしてもかまいません。
これら 3 つの関数は 1 つのマニュアルページで説明しています。このマニュアルページには、個々の関数名 scha_resource_open(3HA)、scha_resource_get(3HA)、または scha_resource_close(3HA) からアクセスできます。
RGM の制御下のリソースの Status および Status_msg プロパティーを設定します。この関数はリソースのモニターによって使用され、モニターから見たリソースの状態を反映します。
scha_resource_setstatus() はリソースモニター専用の関数ですが、任意のプログラムから呼び出すことができます。
scha_resource_setstatus() 関数と同様に、RGM の制御下のリソースの Status および Status_msg プロパティーを設定します。この関数はリソースのモニターによって使用され、モニターから見たリソースの状態を反映します。ただし、この関数ではメソッドを実行するように構成されたゾーンの名前も指定します。
scha_resource_setstatus_zone() は特にリソースモニターが使用しますが、任意のプログラムから呼び出すことができます。
以下の関数は、RGM に登録されているリソースタイプに関する情報にアクセスします。
scha_resourcetype_open() 関数は、リソースへのアクセスを初期化し、scha_resourcetype_get() のハンドルを戻します。scha_resourcetype_get() 関数は、リソースタイプの情報にアクセスします。scha_resourcetype_close() 関数は、ハンドルを無効にし、scha_resourcetype_get() の戻り値に割り当てられているメモリーを解放します。
scha_resourcetype_open() 関数がリソースタイプのハンドルを戻したあとに、クラスタの再構成や管理アクションによって、リソースタイプが変更されることがあります。その結果、scha_resourcetype_get() 関数がハンドルを通じて獲得した情報は正しくない可能性があります。リソースタイプ上でクラスタの再構成や管理アクションが行われた場合、RGM は scha_err_seqid エラーコードを scha_resourcetype_get() 関数に戻し、リソースタイプに関する情報が変更された可能性があることを示します。このエラーメッセージは致命的ではありません。関数は正常に終了します。メッセージを無視し、戻された情報を受け入れることを選択できます。または、現在のハンドルを閉じて新しいハンドルを開き、リソースタイプに関する情報にアクセスしてもかまいません。
これら 3 つの関数は 1 つのマニュアルページで説明しています。このマニュアルページには、個々の関数名 scha_resourcetype_open(3HA)、scha_resourcetype_get(3HA)、または scha_resourcetype_close(3HA) からアクセスできます。
以下の関数を使用すると、リソースグループについての情報にアクセスしたり、リソースグループを再起動できます。
これらの関数は、RGM によって管理されるリソースグループに関する情報にアクセスします。scha_resourcegroup_open() 関数は、リソースグループへのアクセスを初期化し、scha_resourcegroup_get() のハンドルを戻します。scha_resourcegroup_get() 関数は、リソースグループの情報にアクセスします。scha_resourcegroup_close() 関数は、ハンドルを無効にし、scha_resourcegroup_get() の戻り値に割り当てられているメモリーを解放します。
scha_resourcegroup_open() 関数がリソースグループのハンドルを戻したあとに、クラスタの再構成や管理アクションによって、リソースグループが変更されることがあります。その結果、scha_resourcegroup_get() 関数がハンドルを通じて獲得した情報は正しくない可能性があります。リソースグループ上でクラスタの再構成や管理アクションが行われた場合、RGM は scha_err_seqid エラーコードを scha_resourcegroup_get() 関数に戻し、リソースグループに関する情報が変更された可能性があることを示します。このエラーメッセージは致命的ではありません。関数は正常に終了します。メッセージを無視し、戻された情報を受け入れることを選択できます。または、現在のハンドルを閉じて新しいハンドルを開き、リソースグループに関する情報にアクセスしてもかまいません。
これら 3 つの関数は 1 つのマニュアルページで説明しています。このマニュアルページには、個々の関数名 scha_resourcegroup_open(3HA)、scha_resourcegroup_get(3HA)、scha_resourcegroup_close(3HA) からアクセスできます。
RGM の制御下のリソースグループの再起動、または別のノードまたはゾーンへの再配置を要求します。これらの関数の詳細については、scha_control(3HA) および scha_control_zone(3HA) のマニュアルページを参照してください。
以下の関数は、クラスタについての情報にアクセスし、その情報を戻します。
これらの関数は、クラスタについての情報 (クラスタ名、ノードまたはゾーン名、ID、状態、およびリソースグループ) にアクセスします。
scha_cluster_open() 関数がクラスタのハンドルを戻したあとに、再構成や管理アクションによって、クラスタが変更されることがあります。その結果、scha_cluster_get() 関数がハンドルを通じて獲得した情報は正しくない可能性があります。クラスタ上で再構成や管理アクションが行われた場合、RGM は scha_err_seqid エラーコードを scha_cluster_get 関数に戻し、クラスタに関する情報が変更された可能性があることを示します。このエラーメッセージは致命的ではありません。関数は正常に終了します。メッセージを無視し、戻された情報を受け入れることを選択できます。または、現在のハンドルを閉じて新しいハンドルを開き、クラスタに関する情報にアクセスしてもかまいません。
Global_zone リソースタイププロパティーが TRUE に等しいリソースが、ZONE_LOCAL の問い合わせの optag の値を指定して scha_cluster_get() を起動した場合、大域ゾーンの名前が返されます。この場合、呼び出した側のコードでは文字列 :zonename をローカルノード名に連結して、リソースが実際に構成されているゾーンを取得する必要があります。zonename は、-Z zonename コマンド行オプション内のメソッドに渡されるものと同じゾーン名です。コマンド行内に -Z オプションがない場合は、リソースグループが大域ゾーン内に構成されるので、ゾーン名をノード名に連結する必要はありません。
これら 3 つの関数は 1 つのマニュアルページで説明しています。このマニュアルページには、個々の関数名 scha_cluster_open(3HA)、scha_cluster_get(3HA)、または scha_cluster_close(3HA) からアクセスできます。
クラスタログとして使用されるシステムログ機能の数を戻します。戻された番号を Solaris の syslog() 関数で使用すると、イベントと状態メッセージをクラスタログに記録できます。この関数の詳細については、scha_cluster_getlogfacility(3HA) のマニュアルページを参照してください。
関数が呼び出されたクラスタノードの名前を戻します。この関数の詳細については、scha_cluster_getnodename(3HA) のマニュアルページを参照してください。
scha_ 関数のいずれかによって戻されるエラーコードを、対応するエラーメッセージに変換します。この関数を logger コマンドと共に使用すると、メッセージを Solaris システムログ (syslog) に記録できます。この関数の詳細については、scha_strerror(3HA) のマニュアルページを参照してください。
コールバックメソッドは、リソースタイプを実装するために API が提供する重要な要素です。コールバックメソッドを使用すると、RGM は、クラスタのメンバーシップが変更されたとき (ノードあるいはゾーンが起動またはクラッシュしたとき) にクラスタ内のリソースを制御できます。
クライアントプログラムがクラスタシステムの HA サービスを制御するため、コールバックメソッドはスーパーユーザーまたは最大の RBAC ロールのアクセス権を持つ RGM によって実行されます。したがって、このようなコールバックメソッドをインストールおよび管理するときは、ファイルの所有権とアクセス権を制限します。特に、このようなメソッドには、特権付き所有者 (bin や root など) を割り当てます。また、このようなメソッドは、書き込み可能にしてはなりません。
この節では、コールバックメソッドの引数と終了コードについて説明します。
次のカテゴリのコールバックメソッドについて説明します。
制御および初期化メソッド
管理サポートメソッド
ネットワーク関連メソッド
モニター制御メソッド
この節では、メソッドが実行される時点や予想されるリソースへの影響など、コールバックメソッドについて簡単に説明します。コールバックメソッドの詳細については、rt_callbacks(1HA) のマニュアルページを参照してください。
method -R resource-name -T type-name -G group-name
method は、Start や Stop などのコールバックメソッドとして登録されているプログラムのパス名です。リソースタイプのコールバックメソッドは、それらの登録ファイルで宣言します。
コールバックメソッドの引数はすべて、次のようにフラグ付きの値として渡されます。
-R はリソースインスタンスの名前を示します。
-T はリソースのタイプを示します。
-G はリソースが構成されているグループを示します。
このような引数をアクセス関数で使用すると、リソースについての情報を取得できます。
Validate メソッドを呼び出すときは、追加の引数 (リソースのプロパティー値と呼び出しが行われるリソースグループ) を使用します。
詳細については、scha_calls(3HA) のマニュアルページを参照してください。
すべてのコールバックメソッドは、同じ終了コードを持っています。これらの終了コードは、メソッドの呼び出しによるリソースの状態への影響を示すように定義されています。これらの終了コードの詳細については、scha_calls(3HA) のマニュアルページを参照してください。
終了コードには、次の主要な 2 つのカテゴリがあります。
0 – メソッドは成功しました。
ゼロ以外の任意の値 – メソッドは失敗しました。
RGM は、タイムアウトやコアダンプなど、コールバックメソッドの実行の異常終了も処理します。
メソッドは、各ノードまたはゾーン上で syslog() を使用して障害情報を出力するように実装する必要があります。stdout や stderr に書き込まれる出力は、ローカルノードのコンソール上には表示されますが、ユーザーに伝達される保証はありません。
主要な制御および初期化コールバックメソッドは、リソースを起動および停止します。その他のメソッドは、リソース上で初期化と終了コードを実行します。
リソースを含むリソースグループがクラスタノードまたはゾーン上でオンラインになったとき、RGM はそのクラスタノードまたはゾーン上でこのメソッドを実行します。このメソッドは、そのノードまたはゾーン上でリソースを起動します。
ローカルノードまたはゾーン上でリソースが起動され、利用可能になるまで、Start メソッドは終了してはなりません。したがって、Start メソッドは終了する前にリソースをポーリングし、リソースが起動しているかどうかを判断する必要があります。さらに、このメソッドには、十分な長さのタイムアウト値を設定する必要があります。たとえば、データベースデーモンなど特定のリソースが起動するのに時間がかかる場合、そのメソッドには十分な長さのタイムアウト値が必要です。
RGM が Start メソッドの失敗に応答する方法は、Failover_mode プロパティーの設定によって異なります。
リソースタイプ登録 (RTR) ファイルの Start_timeout プロパティーが、リソースの Start メソッドのタイムアウト値を設定します。
リソースを含むリソースグループがクラスタノードまたはゾーン上でオフラインになったとき、RGM はクラスタノードまたはゾーン上でこの必須メソッドを実行します。このメソッドは、リソースを (アクティブであれば) 停止します。
ローカルノードまたはゾーン上でリソースがすべての活動を完全に停止し、すべてのファイル記述子を閉じるまで、Stop メソッドは終了してはなりません。そうしないと、RGM が (実際にはアクティブであるのに) リソースが停止したと判断するため、データが破壊されることがあります。データの破壊を防ぐために最も安全な方法は、リソースに関連するローカルノードまたはゾーン上ですべてのプロセスを停止することです。
Stop メソッドは終了する前にリソースをポーリングし、リソースが停止しているかどうかを判断する必要があります。さらに、このメソッドには、十分な長さのタイムアウト値を設定する必要があります。たとえば、特定のリソース (データベースデーモンなど) が停止するのに時間がかかる場合、そのメソッドには十分な長さのタイムアウト値が必要です。
RGM が Stop メソッドの失敗に応答する方法は、Failover_mode プロパティーの設定によって異なります。「リソースのプロパティー」を参照してください。
RTR ファイルの Stop_timeout プロパティーが、リソースの Stop メソッドのタイムアウト値を設定します。
リソースを管理下に置くとき、RGM はこのオプションメソッドを実行して、リソースの初期化を 1 回だけ実行します。リソースグループが管理されていない状態から管理されている状態に切り替えられるとき、またはすでに管理されているリソースグループでリソースが作成されるとき、RGM はこのメソッドを実行します。このメソッドは、Init_nodes リソースプロパティーにより特定されるノードまたはゾーン上で呼び出されます。
リソースが RGM によって管理されなくなったとき、RGM は Fini メソッドを実行して、そのリソースの使用後のクリーンアップを行います。通常、Fini メソッドは Init メソッドによって実行された初期化をすべて取り消します。
RGM は、次の状況が発生すると、リソースが管理されなくなった各ノードまたはゾーン上で Fini を実行します。
リソースのあるリソースグループが管理されない状態に切り替わる。この場合、RGM はノードリスト内のすべてのノードおよびゾーン上で Fini メソッドを実行します。
管理されているリソースグループからリソースが削除される。この場合、RGM はノードリスト内のすべてのノードおよびゾーン上で Fini メソッドを実行します。
ノードまたはゾーンが、リソースのあるリソースグループのノードリストから削除される。この場合、RGM は削除されたノードおよびゾーン上だけで Fini メソッドを実行します。
「ノードリスト」とは、リソースグループの Nodelist またはリソースタイプの Installed_nodes リストのことです。「ノードリスト」がリソースグループの Nodelist を指すのかリソースタイプの Installed_nodes リストを指すのかは、リソースタイプの Init_nodes プロパティーの設定によって決まります。Init_nodes プロパティーは RG_nodelist または RT_installed_nodes に設定できます。ほとんどのリソースタイプでは、Init_nodes がデフォルトの RG_nodelist に設定されています。この場合は、Init メソッドも Fini メソッドも、リソースグループの Nodelist で指定されたノードまたはゾーン上で実行されます。
Init メソッドが実行する初期化のタイプによって、実装する Fini メソッドが実行する必要のあるクリーンアップのタイプが次のように定義されます。
ノード固有の構成のクリーンアップ。
クラスタ全体にわたる構成のクリーンアップ。
実装する Fini メソッドは、ノード固有の構成だけをクリーンアップするのか、それともノード固有の構成とクラスタ全体にわたる構成の両方をクリーンアップするのかを判断する必要があります。
リソースが特定のノードまたはゾーン上でのみ、管理されなくなった場合、Fini メソッドはノード固有のローカル構成をクリーンアップできます。しかし、ほかのノード上ではリソースは引き続き管理されているため、Fini メソッドはクラスタ全体にわたるグローバル構成をクリーンアップしてはなりません。リソースがクラスタ全体にわたって管理されなくなった場合には、Fini メソッドはノード固有の構成とグローバル構成の両方についてクリーンアップを実行できます。実装する Fini メソッドのコードは、Fini メソッドを実行するローカルのノードまたはゾーンがリソースグループのノードリストに含まれているかどうかを調べることによって、これら 2 つの場合を区別できます。
ローカルのノードまたはゾーンがリソースグループのノードリストに出現している場合は、リソースが削除されようとしているか、管理されない状態に移行しようとしています。リソースはどのノードまたはゾーン上でもアクティブでなくなっています。この場合、実装する Fini メソッドでは、ローカルノード上のノード固有の構成だけでなく、クラスタ全体にわたる構成についてもクリーンアップする必要があります。
ローカルのノードまたはゾーンがリソースグループのノードリストに出現していない場合は、Fini メソッドでそのローカルのノードまたはゾーン上のノード固有の構成をクリーンアップできます。しかし、Fini メソッドでクラスタ全体にわたる構成をクリーンアップしてはなりません。この場合、ほかのノードまたはゾーン上でリソースが引き続きアクティブになっています。
Fini メソッドは順序に依存しない様にコードを作成する必要もあります。つまり、Fini メソッドが以前の実行でリソースをクリーンアップした場合でも、以降の Fini 呼び出しは正常に終了します。
RGM は Init とよく似たこのオプションメソッドを実行し、リソースの所属リソースグループが RGM の管理下に置かれたあと、クラスタを結合するノードまたはゾーン上のリソースを初期化します。Init_nodes リソースプロパティーにより特定されるノードまたはゾーン上で、RGM はこのメソッドを実行します。起動または再起動の結果としてノードまたはゾーンがクラスタに結合または再結合したときに、Boot メソッドは呼び出されます。
Global_zone リソースタイププロパティーが TRUE に等しい場合、リソースを含むリソースグループが非大域ゾーンで動作するように構成されているときでも、メソッドは大域ゾーンで実行されます。
Init、Fini、または Boot メソッドが失敗した場合は、エラーメッセージがシステムログに書き込まれます。ただし、それ以外は RGM によるリソース管理に影響しません。
リソース上での管理アクションには、リソースプロパティーの設定と変更があります。Validate および Update コールバックメソッドを使用してリソースタイプを実装すると、このような管理アクションを実行できます。
リソースの作成時や、クラスタ管理者によるリソースまたはリソースグループのプロパティーの更新時、RGM は、このオプションメソッドを呼び出します。このメソッドは、リソースタイプの Init_nodes プロパティーにより特定されるクラスタノードまたはゾーンのセットに対して呼び出されます。Validate メソッドは作成または更新が行われる前に呼び出されます。任意のノードまたはゾーン上でメソッドから失敗の終了コードが戻ってくると、作成または更新は取り消されます。
Validate は、クラスタ管理者によってリソースプロパティーまたはリソースグループプロパティーが変更されたときだけ呼び出されます。RGM によってプロパティーが設定されたときや、モニターによって Status および Status_msg リソースプロパティーが設定されたときは、このメソッドは呼び出されません。
RGM は、このオプションメソッドを実行して、プロパティーが変更されたことを実行中のリソースに通知します。管理アクションがリソースまたはそのグループのプロパティーの設定に成功したあとに、RGM は Update を実行します。このメソッドは、リソースがオンラインであるノードまたはゾーン上で呼び出されます。このメソッドは、API アクセス関数を使用し、アクティブなリソースに影響する可能性があるプロパティー値を読み取り、その値に従って実行中のリソースを調節します。
Update メソッドが失敗した場合は、エラーメッセージがシステムログに書き込まれます。ただし、それ以外は RGM によるリソース管理に影響しません。
ネットワークアドレスリソースを使用するサービスでは、ネットワークアドレス構成から始まる特定の順番で、起動手順または停止手順を実行する必要があります。任意のコールバックメソッドの Prenet_start と Postnet_stop を使用してリソースタイプを実装すると、関連するネットワークアドレスが「起動」に構成される前、または、「停止」に構成されたあとに、特別な起動アクションとシャットダウンアクションを実行できます。
このオプションメソッドを呼び出して、同じリソースグループ内のネットワークアドレスが構成される前に特殊な起動アクションを実行することができます。
このオプションメソッドを呼び出して、同じリソースグループ内のネットワークアドレスを停止状態に構成したあとに特殊な終了アクションを実行することができます。
リソースタイプの実装は、オプションとして、リソースの性能を監視したり、その状態を報告したり、リソースの障害に対処するようなプログラムを含むことができます。Monitor_start、Monitor_stop、 Monitor_check メソッドは、リソースタイプ実装でのリソースモニターの実装をサポートします。
このオプションメソッドを呼び出して、リソースの起動後にリソースの監視を開始することができます。
この任意メソッドは、リソースが停止する前に呼び出され、リソースのモニターを停止します。
このオプションメソッドを呼び出して、リソースグループをノードまたはゾーンに再配置する前に、そのノードまたはゾーンの信頼性を査定することができます。Monitor_check メソッドは、並行して実行中のそのほかのメソッドと競合しない方法で実装する必要があります。