Sun Cluster 3.0 データサービス開発ガイド

第 4 章 RMAPI リファレンス

この章では、RMAPI (Resource Management (リソース管理) API) を構成するアクセス関数やコールバックメソッドに関する情報を提供します。ここでは、各関数やメソッドについて簡単に説明します。詳細は、Resource Management API のマニュアルページを参照してください。

この章の内容は、次のとおりです。

「RMAPI アクセスメソッド」 - シェルスクリプトコマンド (1HA) と C 関数 (3HA)
- scha_resource_get(1HA) (scha_resource_open_get_close(3HA))
- scha_resource_setstatus(1HA)(3HA)
- scha_resourcetype_get(1HA) scha_resourcetype__open_get_close(3HA)
- scha_resource_resourcegroup_get(1HA)(3HA) scha_resource_resourcegroup_open_get_close(3HA)
- scha_control(1HA)(3HA)
- scha_cluster_get(1HA) scha_resource_cluster_open_get_close(3HA)
- scha_cluster_getlogfacility(3HA)
- scha_cluster_getnodename(3HA)
- scha_strerror(3HA)
「RMAPI コールバックメソッド」 - rt_callbacks(1HA) のマニュアルページで説明されている内容
- START
- STOP
- INIT
- FINI
- BOOT
- PRENET_START
- PRENET_STOP
- MONITOR_START
- MONITOR_STOP
- MONITOR_CHECK
- UPDATE
- VALIDATES

RMAPI アクセスメソッド

API は、リソース、リソースタイプ、リソースグループのプロパティ、および他のクラスタ情報にアクセスするための関数を提供します。これらの関数はシェルコマンドと C 関数の両方の形で提供されるため、リソースタイプの開発者はシェルスクリプトまたは C プログラムのどちらでも制御プログラムを実装できます。

RMAPI シェルコマンド

シェルコマンドは、クラスタの RGM によって制御されるサービスを表すリソースタイプのコールバックメソッドを、シェルスクリプトで実装するときに使用します。このコマンドを使用すると、次のことを行えます。

リソース、リソースタイプ、リソースグループ、クラスタについての情報にアクセスする。
モニターと併用し、リソースの Status プロパティと Status_msg プロパティを設定する。
リソースグループの再起動と再配置を要求する。

注 -

この節では、シェルコマンドについて簡単に説明します。詳細は各コマンドの (1HA) マニュアルページを参照してください。特に注記しない限り、各コマンドと同じ名前のマニュアルページがあります。

RMAPI リソースコマンド

以下のコマンドを使用すると、リソースについての情報にアクセスしたり、リソースの Status プロパティや Status_msg プロパティを設定できます。

scha_resource_get(1HA) - RGM の制御下にあるリソースまたはリソースタイプについての情報にアクセスします。このコマンドは、C 関数 scha_resource_get(3HA) と同じ情報を提供します。
scha_resource_setstatus(1HA) - RGM の制御下にあるリソースの Status プロパティと Status_msg プロパティを設定します。このコマンドはリソースのモニターによって使用され、モニターから見たリソースの状態を反映します。このコマンドは、C 関数 scha_resource_setstatus(3HA) と同じ機能を提供します。

注 -
scha_resource_setstatus はリソースモニター専用の関数ですが、任意のプログラムから呼び出すことができます。

リソースタイプコマンド

このコマンドは、RGM に登録されているリソースタイプについての情報にアクセスします。

scha_resourcetype_get(1HA) - このコマンドは、C 関数 scha_resourcetype_get(3HA) と同じ機能を提供します。

リソースグループコマンド

以下のコマンドを使用すると、リソースグループについての情報にアクセスしたり、リソースグループを再起動できます。

scha_resourcegroup_get(1HA) - RGM の制御下にあるリソースグループについての情報にアクセスします。このコマンドは、C 関数 scha_resourcegroup_get(3HA) と同じ機能を提供します。
scha_control(1HA) - RGM の制御下にあるリソースグループの再起動、または、異なるノードへの再配置を要求します。このコマンドは、C 関数 scha_control(3HA) と同じ機能を提供します。

クラスタコマンド

このコマンドは、クラスタについての情報 (ノード名、ノード ID、ノードの状態、クラスタ名、リソースグループなど) にアクセスします。

scha_cluster_get(1HA) - このコマンドは、C 関数 scha_cluster_get(3HA) と同じ情報を提供します。

C 関数

C 関数は、クラスタの RGM によって制御されるサービスを表すリソースタイプのコールバックメソッドを、C プログラムで実装するときに使用します。この関数を使用すると、次のことを行えます。

リソース、リソースタイプ、リソースグループ、クラスタについての情報にアクセスする。
モニターと併用し、リソースの Status プロパティと Status_msg プロパティを設定する。
リソースグループの再起動と再配置を要求する。
エラーコードを適切なエラーメッセージに変換する。

注 -

この節では、C 関数について簡単に説明します。詳細は各関数の (3HA) マニュアルページを参照してください。特に注記しない限り、各関数と同じ名前のマニュアルページがあります。C 関数の出力引数や戻りコードについては、scha_calls(3HA) のマニュアルページを参照してください。

リソース関数

以下の関数は、RGM に管理されているリソースについての情報にアクセスします。モニターから見たリソースの状態を表します。

scha_resource_open(3HA)、scha_resource_get(3HA)、 scha_resource_close(3HA) - これらの関数は一緒に、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) でアクセスできます。
scha_resource_setstatus(3HA) - RGM の制御下にあるリソースの Status プロパティと Status_msg プロパティを設定します。この関数はリソースのモニターによって使用され、モニターから見たリソースの状態を反映します。

注 -
scha_resource_setstatus はリソースモニター専用の関数ですが、任意のプログラムから呼び出すことができます。

リソースタイプ関数

これらの関数は一緒に、RGM に登録されているリソースタイプについての情報にアクセスします。

scha_resourcetype_open(3HA)、scha_resourcetype_get(3HA)、 scha_resourcetype_close(3HA)- 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) でアクセスできます。

リソースグループ関数

以下の関数を使用すると、リソースグループについての情報にアクセスしたり、リソースグループを再起動できます。

scha_resourcegroup_open(3HA)、scha_resourcegroup_get(3HA)、 scha_resourcegroup_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) でアクセスできます。
scha_control(3HA)- RGM の制御下にあるリソースグループの再起動、または、異なるノードへの再配置を要求します。

クラスタ関数

以下の関数は、クラスタについての情報にアクセスし、その情報を戻します。

scha_cluster_open(3HA)、scha_cluster_get(3HA)、 scha_cluster_close(3HA) - これらの関数は一緒に、クラスタについての情報 (ノード名、ノード ID、ノードの状態、クラスタ名、リソースグループなど) にアクセスします。

これら 3 つの関数は 1 つのマニュアルページ内で説明しています。このマニュアルページには、個々の関数名 scha_cluster_open(3HA)、scha_cluster_get(3HA)、scha_cluster_close(3HA) でアクセスできます。

scha_cluster_open 関数がクラスタのハンドルを戻した後に、再構成や管理アクションによって、クラスタが変更されることがあります。この場合、scha_cluster_get 関数がハンドルを通じて獲得した情報は正しくない可能性があります。クラスタ上でクラスタの再構成や管理アクションが行われた場合、RGM は scha_err_seqid エラーコードを scha_cluster_get 関数に戻し、クラスタが変更されたことを示します。このメッセージは致命的なエラーメッセージではないため、関数は正常に終了します。したがって、このメッセージは無視してもかまいません。また、現在のハンドルを閉じて新しいハンドルを開き、クラスタの情報にアクセスし直してもかまいません。
scha_cluster_getlogfacility(3HA) - クラスタログとして使用されているシステムログ機能番号を戻します。戻された番号を Solaris の syslog(3) 関数で使用すると、イベントと状態メッセージをクラスタログに記録できます。
scha_cluster_getnodename(3HA) - 関数が呼び出されるクラスタノードの名前を戻します。

ユーティリティ関数

この関数は、エラーコードをエラーメッセージに変換します。

scha_strerror(3HA) - scha_ 関数の 1 つから戻されるエラーコードを適切なエラーメッセージに変換します。この関数を logger(1) と共に使用すると、メッセージをシステムログ (syslog(3)) に記録できます。

RMAPI コールバックメソッド

コールバックメソッドは、リソースタイプを実装するための API が提供する重要な要素です。コールバックメソッドを使用すると、RGM は、クラスタのメンバーシップが変更されたとき (ノードが起動またはクラッシュしたとき) にクラスタ内のリソースを制御できます。

注 -

クライアントプログラムがクラスタシステム上の HA サービスを制御するため、コールバックメソッドはルートのアクセス権を持つ RGM によって実行されます。したがって、このようなコールバックメソッドをインストールおよび管理するときは、ファイルの所有権とアクセス権を制限します。特に、このようなコールバックメソッドには、特権付き所有者 (bin や root など) を割り当てます。さらに、このようなコールバックメソッドは、書き込み可能にしてはなりません。

この節では、コールバックメソッドの引数と終了コードについて説明し、次のカテゴリのコールバックメソッドについて説明します。

制御および初期化メソッド
管理サポートメソッド
ネットワーク関連メソッド
モニター制御メソッド

注 -

この節では、メソッドが呼び出されるタイミングや予想されるリソースへの影響など、コールバックメソッドについて簡単に説明します。詳細は、rt_callbacks(1HA) のマニュアルページを参照してください。

メソッドの引数

RGM はコールバックメソッドを呼び出すとき、次のような引数を使用します。

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

method は、START や STOP などのコールバックメソッドとして登録されているプログラムのパス名です。リソースタイプのコールバックメソッドは、それらの登録ファイルで宣言します。

コールバックメソッドの引数はすべて、フラグ付きの値として渡されます。-R はリソースインスタンスの名前を示し、-T はリソースのタイプを示し、-G はリソースが構成されているグループを示します。このような引数をアクセス関数で使用すると、リソースについての情報を取得できます。

VALIDATE メソッドを呼び出すときは、追加の引数 (リソースのプロパティ値と呼び出されるリソースグループ) を使用します。

詳細は、rt_callbacks(1HA) のマニュアルページを参照してください。

終了コード

終了コードは、すべてのコールバックメソッドで共通で、メソッドの呼び出しによるリソースの状態への影響を示すように定義されています。これらすべての終了コードについては、scha_calls(3HA) のマニュアルページを参照してください。

0 (ゼロ) - メソッドは成功しました。
ゼロ以外の任意の値 - メソッドは失敗しました。

RGM は、コールバックメソッドの実行の異常終了 (タイムアウトやコアダンプ) も処理します。

メソッドは、各ノード上で syslog(3) を使用して障害情報を出力するように実装する必要があります。stdout や stderr に書き込まれる出力は、ローカルノードのコンソール上には表示されますが、それをユーザーが確認するかどうかは保証できないためです。

制御および初期化コールバックメソッド

制御および初期化コールバックメソッドは、主に、リソースを起動および停止します。その他にも、リソース上で初期化と終了コードを実行します。

START - この必須メソッドは、リソースを含むリソースグループをクラスタノード上でオンラインにするとき、そのノード上で呼び出されます。このメソッドは、そのノード上でリソースを起動します。

ローカルノード上でリソースが起動され、利用可能になるまで、START メソッドは終了してはなりません。したがって、START メソッドは終了する前にリソースをポーリングし、リソースが起動しているかどうかを判断する必要があります。さらに、このメソッドには、十分な長さのタイムアウト値を設定する必要があります。たとえば、あるリソース (データベースデーモンなど) が起動するのに時間がかかる場合、そのメソッドには十分な長さのタイムアウト値を設定する必要があります。

RGM が START メソッドの失敗に応答する方法は、Failover_mode プロパティの設定によって異なります (表 A-2 を参照)。

リソースの START メソッドのタイムアウト値を設定するには、リソースタイプ登録ファイルの START_TIMEOUT プロパティを使用します。
STOP - この必須メソッドは、リソースを含むリソースグループをクラスタノード上でオフラインにするとき、そのノード上で呼び出されます。このメソッドは、リソースを (アクティブであれば) 停止します。

ローカルノード上でリソースがすべての活動を完全に停止し、すべてのファイル記述子を閉じるまで、STOP メソッドは終了してはなりません。そうしないと、RGM が (実際にはアクティブであるのに) リソースが停止したと判断するため、データが破壊されることがあります。データの破壊を防ぐために最も安全な方法は、ローカルノード上でリソースに関連するすべてのプロセスを停止することです。

STOP メソッドは終了する前にリソースをポーリングし、リソースが停止しているかどうかを判断する必要があります。さらに、このメソッドには、十分な長さのタイムアウト値を設定する必要があります。たとえば、あるリソース (データベースデーモンなど) が停止するのに時間がかかる場合、そのメソッドには十分長めのタイムアウト値を設定する必要があります。

RGM が STOP メソッドの失敗に応答する方法は、Failover_mode プロパティの設定によって異なります (表 A-2 を参照)。

リソースの STOP メソッドのタイムアウト値を設定するには、リソースタイプ登録ファイルの STOP_TIMEOUT プロパティを使用します。
INIT - この任意メソッドは、リソースを管理下に置くとき (リソースが属しているリソースグループを管理していない状態から管理している状態に切り替えるとき、または、すでに管理されているリソースグループでリソースを作成するとき) に呼び出され、一度だけリソースの初期化を実行します。このメソッドは、Init_nodes リソースプロパティが示すノード上で呼び出されます。
FINI - この任意メソッドは、リソースを管理下から外すとき (リソースが属しているリソースグループを管理していない状態に切り替えるとき、または、すでに管理されているリソースグループからリソースを削除するとき) に呼び出され、リソースをクリーンアップします。このメソッドは、Init_nodes リソースプロパティが示すノード上で呼び出されます。
BOOT - この任意メソッドは、INIT と同様にリソースの初期化を実行します。ただし、リソースを含むリソースグループがすでに RGM の管理下に置かれている状態で、新たにクラスタに参加したノード上で呼び出されます。このメソッドは、Init_nodes リソースプロパティが示すノード上で呼び出されます。BOOT メソッドは、起動または再起動の結果とし、ノードがクラスタに結合または再結合したときに呼び出されます。

注 -

INIT、FINI、BOOT メソッドが失敗すると、syslog(3) 関数がエラーメッセージを生成しますが、それ以外は RGM のリソース管理に影響しません。

管理サポートメソッド

リソース上での管理アクションには、リソースプロパティの設定と変更があります。VALIDATE と UPDATE コールバックメソッドを使用してリソースタイプを実装すると、このような管理アクションを行うことができます。

VALIDATE - この任意メソッドは、リソースが作成されるとき、および、リソースまたはリソースグループ (リソースを含む) のプロパティが管理アクションによって更新されるときに呼び出されます。このメソッドは、リソースタイプの Init_nodes プロパティが示す複数のクラスタノード上で呼び出されます。VALIDATE は、作成または更新が行われる前に呼び出されます。任意のノード上でメソッドから失敗の終了コードが戻ると、作成または更新は取り消されます。

VALIDATE が呼び出されるのは、リソースまたはリソースグループのプロパティが管理アクションを通じて変更されたときだけです。RGM がプロパティを設定したときや、モニターがリソースプロパティ Status や Status_msg を設定したときではありません。
UPDATE - この任意メソッドは、プロパティが変更されたことを実行中のリソースに通知します。UPDATE は、管理アクションがリソースまたはリソースグループのプロパティの設定に成功した後に呼び出されます。このメソッドは、リソースがオンラインであるノード上で呼び出されます。このメソッドは、API アクセス関数を使用し、アクティブなリソースに影響する可能性があるプロパティ値を読み取り、その値に従って実行中のリソースを調節します。

UPDATE メソッドが失敗すると、syslog(3) 関数がエラーメッセージを生成しますが、それ以外は RGM のリソース管理に影響しません。

ネットワーク関連コールバックメソッド

ネットワークアドレスリソースを使用するサービスでは、ネットワークアドレス構成に相対的な順番で、起動手順または停止手順を行う必要があります。任意コールバックメソッドの PRENET_START と POSTNET_STOP を使用してリソースタイプを実装すると、関連するネットワークアドレスが「起動」に構成される前、または、「停止」に構成された後に、特別な起動アクションまたはシャットダウンアクションを行うことができます。

PRENET_START - この任意メソッドは、同じリソースグループ内のネットワークアドレスが「起動」に構成される前に呼び出され、特別な起動アクションを行います。
POSTNET_STOP - この任意メソッドは、同じリソースグループ内のネットワークアドレスが「停止」に構成された後に呼び出され、特別なシャットダウンアクションを行います。

モニター制御コールバックメソッド

リソースタイプは、オプションとして、リソースの性能を監視したり、その状態を報告したり、リソースの障害に対処するようなプログラムを含むようにも実装できます。MONITOR_START、MONITOR_STOP、MONITOR_CHECK メソッドは、リソースタイプへのリソースモニターの実装をサポートします。

MONITOR_START - この任意メソッドは、リソースが起動した後に呼び出され、リソースを監視するモニターを起動します。
MONITOR_STOP - この任意メソッドは、リソースが停止する前に呼び出され、リソースのモニターを停止します。
MONITOR_CHECK - この任意メソッドは、リソースグループがノードに再配置される前に呼び出され、ノードの信頼性を査定します。