test

Sun Cluster Entwicklerhandbuch Datendienste für Solaris OS

Kapitel 4 Ressourcenverwaltungs-API-Referenz

Dieses Kapitel erläutert die Zugriffsfunktionen und Rückmeldemethoden, aus denen sich die Ressourcenverwaltungs-API (RMAPI) zusammensetzt. Es listet alle Funktionen und Methoden auf und beschreibt sie kurz. Als maßgebliche Referenz für diese Funktionen und Methoden wird jedoch auf die RMAPI-Online-Dokumentation verwiesen.

In diesem Kapitel finden Sie folgende Informationen:

RMAPI-Zugriffsmethoden

Die API stellt Funktionen bereit, mit denen auf Ressourcen-, Ressourcentyp- und Ressourcengruppeneigenschaften sowie auf anderweitige Cluster-Informationen zugegriffen werden kann. Diese Funktionen sind sowohl in Form von Shell-Befehlen als auch als C-Funktionen vorhanden. So können die Ressourcentyphersteller Steuerprogramme als Shell-Skripts oder als C-Programme implementieren.

RMAPI-Shell-Befehle

Shell-Befehle werden in Shell-Skript-Implementierungen der Rückmeldemethoden für Ressourcentypen verwendet, die von RGM des Clusters gesteuerte Dienste darstellen. Diese Befehle können zu folgenden Zwecken eingesetzt werden:

Hinweis –

Dieser Abschnitt enthält kurze Beschreibungen der Shell-Befehle. Als maßgebliche Referenz für die Shell-Befehle wird jedoch auf die einzelnen Seiten der 1HA-Online-Dokumentation verwiesen. Für jeden Befehl ist eine gleichnamige Seite in der Online-Dokumentation vorhanden, sofern nicht anders angegeben.

RMAPI-Ressourcenbefehle

Mit diesen Befehlen können Sie auf Informationen über eine Ressource zugreifen oder die Status- und Status_msg-Eigenschaften einer Ressource einstellen.

scha_resource_get

Greift auf Informationen über eine Ressource bzw. einen Ressourcentyp unter RGM-Steuerung zu. Stellt die gleichen Informationen wie die scha_resource_get()-Funktion bereit.

scha_resource_setstatus

Stellt die Status- und Status_msg-Eigenschaften einer Ressource unter RGM-Steuerung ein. Wird vom Ressourcen-Monitor verwendet, um den vom Monitor wahrgenommenen Ressourcenzustand anzugeben. Bietet die gleiche Funktionalität wie die C-Funktion scha_resource_setstatus().

Hinweis –

scha_resource_setstatus()ist zwar für einen Ressourcen-Monitor besonders nützlich, kann jedoch von jedem beliebigen Programm aufgerufen werden.

Ressourcentypbefehl

Dieser Befehl greift auf Informationen über einen bei RGM registrierten Ressourcentyp zu.

scha_resourcetype_get

Dieser Befehl bietet die gleiche Funktionalität wie die C-Funktion scha_resourcetype_get().

Ressourcengruppenbefehle

Mit diesen Befehlen können Sie auf Informationen über eine Ressourcengruppe zugreifen bzw. diese neu starten.

scha_resourcegroup_get

Greift auf Informationen über eine Ressourcengruppe unter RGM-Steuerung zu. Dieser Befehl bietet die gleiche Funktionalität wie die C-Funktion scha_resourcetype_get().

scha_control

Fordert den Neustart einer Ressourcengruppe unter RGM-Steuerung bzw. die Verschiebung zu einem anderen Knoten an. Dieser Befehl bietet die gleiche Funktionalität wie die C-Funktion scha_control().

Cluster-Befehl

Dieser Befehl greift auf Informationen über einen Cluster zu, wie Knotennamen, IDs, Zustand, Cluster-Name, Ressourcengruppen usw.

scha_cluster_get

Dieser Befehl stellt die gleichen Informationen wie die C-Funktion scha_cluster_get() bereit.

C-Funktionen

C-Funktionen werden in C-Programmimplementierungen der Rückmeldemethoden für Ressourcentypen eingesetzt, die Dienste unter RGM-Steuerung des Clusters darstellen. Sie können diese Funktionen zu folgenden Zwecken einsetzen:

Hinweis –

Dieser Abschnitt enthält zwar kurze Beschreibungen der C-Funktionen. Als maßgebliche Referenz für diese Funktionen wird jedoch auf die einzelnen Seiten der (3HA)-Online-Dokumentation verwiesen. Für jede Funktion ist eine gleichnamige Seite in der Online-Dokumentation vorhanden, sofern nicht anders angegeben. Informationen zu Ausgabeargumenten und Rückgabecodes der C-Funktionen finden Sie in der Online-Dokumentation unter scha_calls(3HA).

Ressourcenfunktionen

Diese Funktionen greifen auf Informationen über eine von RGM verwaltete Ressource zu bzw. geben den vom Monitor festgestellten Zustand der Ressource an.

scha_resource_open(), scha_resource_get () und scha_resource_close()

Zusammen greifen diese Funktionen auf Informationen über eine von RGM verwaltete Ressource zu. Die scha_resource_open()-Funktion initialisiert den Zugriff auf eine Ressource und gibt ein Handle für scha_resource_get() zurück, womit auf die Ressourceninformationen zugegriffen wird. Die scha_resource_close()-Funktion invalidiert das Handle und gibt den für die Rückgabewerte von scha_resource_get() zugewiesenen Speicherplatz frei.

Eine Ressource kann durch eine Cluster-Rekonfiguration oder einen Verwaltungsbefehl geändert werden, nachdem scha_resource_open() das Handle für die Ressource zurückgegeben hat. In diesem Fall können die von scha_resource_get() über das Handle abgerufenen Informationen falsch sein. Im Fall einer Cluster-Rekonfiguration oder einer Verwaltungsaktion an einer Ressource gibt RGM den Fehlercode scha_err_seqid an scha_resource_get() zurück, um anzugeben, dass sich die Ressourceninformationen geändert haben könnten. Diese Meldung gibt keinen schwerwiegenden Fehler an; die Funktion gibt Erfolg zurück. Sie können die Meldung ignorieren und die zurückgegebenen Informationen akzeptieren, oder das aktuelle Handle schließen und ein neues Handle zum Zugreifen auf Ressurceninformationen öffnen.

Eine gemeinsame Online-Dokumentationsseite beschreibt diese drei Funktionen. Auf diese Seite können Sie über jede der einzelnen Funktionen, scha_resource_open(3HA), scha_resource_get(3HA) oder scha_resource_close(3HA) zugreifen.

scha_resource_setstatus()

Stellt die Status- und Status_msg-Eigenschaften einer Ressource unter RGM-Steuerung ein. Der Ressourcen-Monitor verwendet diese Funktion, um den Ressourcenzustand anzugeben.

Hinweis –

scha_resource_setstatus()ist zwar für einen Ressourcen-Monitor besonders nützlich, kann jedoch von jedem beliebigen Programm aufgerufen werden.

Ressourcentypfunktionen

Diese Funktionen greifen gemeinsam auf Informationen über einen bei RGM registrierten Ressourcentyp zu.

scha_resourcetype_open(), scha_resourcetype_get(), scha_resourcetype_close()

Die Funktion scha_resourcetype_open() initialisiert den Zugriff auf eine Ressource und gibt ein Handle für scha_resourcetype_get() zurück, womit auf die Ressourcentypinformationen zugegriffen wird. Die Funktion scha_resourcetype_close() invalidiert das Handle und gibt den für die Rückgabewerte von scha_resourcetype_get() zugewiesenen Speicherplatz frei.

Ein Ressourcentyp kann durch eine Cluster-Rekonfiguration oder einen Verwaltungsbefehl geändert werden, nachdem scha_resourcetype_open() das Ressourcentyp-Handle zurückgegeben hat. In diesem Fall können die von scha_resourcetype_get () über das Handle abgerufenen Informationen falsch sein. Im Fall einer Cluster-Rekonfiguration oder einer Verwaltungsaktion an einem Ressourcentyp gibt RGM den Fehlercode scha_err_seqid an scha_resourcetype_get() zurück, um anzugeben, dass sich die Ressourcentypinformationen geändert haben könnten. Diese Meldung gibt keinen schwerwiegenden Fehler an; die Funktion gibt Erfolg zurück. Sie können die Meldung ignorieren und die zurückgegebenen Informationen akzeptieren, oder das aktuelle Handle schließen und ein neues Handle zum Zugreifen auf Ressourcentypinformationen öffnen.

Eine gemeinsame Online-Dokumentationsseite beschreibt diese drei Funktionen. Auf diese Seite können Sie über jede der einzelnen Funktionen, scha_resourcetype_open(3HA), scha_resourcetype_get(3HA) oder scha_resourcetype_close(3HA) zugreifen.

Ressourcengruppenfunktionen

Mit diesen Funktionen können Sie auf Informationen über eine Ressourcengruppe zugreifen bzw. sie neu starten.

scha_resourcegroup_open(3HA), scha_resourcegroup_get(3HA) und scha_resourcegroup_close(3HA)

Zusammen greifen diese Funktionen auf eine von RGM verwaltete Ressourcengruppe zu. Die Funktion scha_resourcegroup_open() initialisiert den Zugriff auf eine Ressourcengruppe und gibt ein Handle für scha_resourcegroup_get() zurück, womit auf die Ressourcengruppeninformationen zugegriffen wird. Die Funktion scha_resourcegroup_close() invalidiert das Handle und gibt den für die Rückgabewerte von scha_resourcegroup_get() zugewiesenen Speicherplatz frei.

Eine Ressourcengruppe kann durch eine Cluster-Rekonfiguration oder eine Verwaltungsaktion geändert werden, nachdem scha_resourcegroup_open() das Ressourcengruppen-Handle zurückgegeben hat. In diesem Fall können die von scha_resourcegroup_get() über das Handle abgerufenen Informationen falsch sein. Im Fall einer Cluster-Rekonfiguration oder einer Verwaltungsaktion an einer Ressourcengruppe gibt RGM den Fehlercode scha_err_seqid an scha_resourcegroup_get() zurück, um anzugeben, dass sich die Ressourcengruppeninformationen geändert haben könnten. Diese Meldung gibt keinen schwerwiegenden Fehler an; die Funktion gibt Erfolg zurück. Sie können die Meldung ignorieren und die zurückgegebenen Informationen akzeptieren, oder das aktuelle Handle schließen und ein neues Handle zum Zugreifen auf Ressourcengruppeninformationen öffnen.

scha_control( 3HA)

Fordert den Neustart einer Ressourcengruppe unter RGM-Steuerung bzw. die Verschiebung zu einem anderen Knoten an.

Cluster-Funktionen

Diese Funktionen greifen auf Informationen über einen Cluster zu bzw. geben diese zurück.

scha_cluster_open(3HA), scha_cluster_get(3HA), scha_cluster_close(3HA)

Diese Funktionen greifen gemeinsam auf Informationen über einen Cluster zu, wie Knotennamen, IDs, Zustand, Cluster-Name, Ressourcengruppe usw.

Ein Cluster kann — durch Rekonfiguration oder eine Verwaltungsaktion — geändert werden, nachdem scha_cluster_open() das Cluster-Handle zurückgegeben hat. In diesem Fall können die von scha_cluster_get() über das Handle abgerufenen Informationen falsch sein. Im Fall einer Cluster-Rekonfiguration oder einer Verwaltungsaktion an einem Cluster gibt RGM den Fehlercode scha_err_seqid an scha_cluster_get() zurück, um anzugeben, dass sich die Cluster-Informationen geändert haben könnten. Diese Meldung gibt keinen schwerwiegenden Fehler an; die Funktion gibt Erfolg zurück. Sie können die Meldung ignorieren und die zurückgegebenen Informationen akzeptieren, oder das aktuelle Handle schließen und ein neues Handle zum Zugreifen auf Cluster-Informationen öffnen.

scha_cluster_getlogfacility(3HA)

Gibt die Nummer der Systemprotokollierung zurück, die als Cluster-Protokoll verwendet wird. Verwendet den von der Solaris-Funktion syslog() zurückgegebenen Wert zum Aufzeichnen von Ereignissen und Statusmeldungen im Cluster-Protokoll.

scha_cluster_getnodename(3HA)

Gibt den Namen des Cluster-Knotens zurück, auf dem die Funktion aufgerufen wird.

Dienstprogrammfunktion

Diese Funktion konvertiert einen Fehlercode in eine Fehlermeldung.

scha_strerror( 3HA)

Überträgt einen Fehlercode — zurückgegeben von einer der scha_-Funktionen — in die entsprechende Fehlermeldung. Verwenden Sie diese Funktion mit logger, um Meldungen im Systemprotokoll (syslog) zu protokollieren.

RMAPI-Rückmeldemethoden

Rückmeldemethoden sind die von der API bereitgestellten Schlüsselelemente für eine Ressourcentypimplementierung. Mithilfe der Rückmeldemethoden kann RGM Ressourcen im Cluster steuern, wenn eine Änderung der Cluster-Mitgliedschaft eintritt, wie zum Beispiel ein Knotenstart oder -absturz.

Hinweis –

Die Rückmeldemethoden werden von RGM mit Root-Berechtigungen ausgeführt, weil die Client-Programme HA-Dienste im Cluster-System steuern. Installieren und verwalten Sie diese Methoden mit eingeschränkter Dateieigentümerschaft und eingeschränkten Berechtigungen. Geben Sie ihnen einen eigens privilegierten Eigentümer, wie bin oder root, und erteilen Sie nur Lesezugriff.

Dieser Abschnitt beschreibt Rückmeldemethodenargumente und Beendigungscodes. Die Rückmeldemethoden werden in folgenden Kategorien aufgelistet und beschrieben:

Hinweis –

Dieser Abschnitt enthält zwar kurze Beschreibungen der Rückmeldemethoden und beschreibt den Zeitpunkt, zu dem die Methode aufgerufen wird und welche Auswirkung dies auf die Ressource haben soll. Als maßgebliche Referenz für die Rückmeldemethoden wird jedoch auf die Online-Dokumentation rt_callbacks(1HA) verwiesen.

Methodenargumente

RGM ruft Rückmeldemethoden folgendermaßen auf: 


Methode -R Ressourcenname -T Typname -G Gruppenname

Die Methode ist der Pfadname des Programms, das als Start, Stop oder sonstige Rückmeldung registriert ist. Die Rückmeldemethoden eines Ressourcentyps werden in dessen Registrierungsdatei deklariert.

Alle Rückmeldemethodenargumente werden als Werte mit Flags übergeben, wobei -R den Namen der Ressourceninstanz, -T den Ressourcentyp und -G die Gruppe angibt, in der die Ressource konfiguriert wird. Verwenden Sie die Argumente mit Zugriffsfunktionen, um Informationen über die Ressource abzurufen.

Die Validate-Methode wird mit zusätzlichen Argumenten aufgerufen, das heißt mit den Eigenschaftswerten der Ressource und Ressourcengruppe, in denen sie aufgerufen wird.

Weitere Informationen hierzu finden Sie unter scha_calls(3HA).

Beendigungscodes

Für alle Rückmeldemethoden sind die gleichen Beendigungscodes definiert, um die Auswirkung des Methodenaufrufs auf den Ressourcenzustand anzugeben. Eine Beschreibung der Beendigungscodes finden Sie in der Online-Dokumentation unter scha_calls(3HA). Die Beendigungscodes sind:

RGM verwaltet auch außergewöhnliche Fehlschläge der Rückmeldemethodenausführung, wie Zeitüberschreitungen oder Speicherabbilder.

Methodenimplementierungen müssen die Fehlschlaginformationen für jeden Knoten über syslog ausgeben. Wenn die Ausgabe an stdout oder stderr geschrieben wird, ist nicht garantiert, dass sie dem Benutzer zugestellt wird, auch wenn sie aktuell auf der Konsole des lokalen Knotens angezeigt wird.

Steuerungs- und Initialisierungs-Rückmeldemethoden

Die primären Steuerungs- und Initialisierungs-Rückmeldemethoden starten und stoppen eine Ressource. Andere Methoden führen für eine Ressource Initialisierungs- und Beendigungscode aus.

Start

Diese erforderliche Methode wird auf einem Cluster-Knoten aufgerufen, wenn die Ressourcengruppe mit der Ressource auf diesem Knoten online gebracht wird. Die Methode aktiviert die Ressource auf dem Knoten.

Eine Start-Methode darf erst dann beendet werden, wenn die von ihr aktivierte Ressource gestartet wurde und auf dem lokalen Knoten verfügbar ist. Daher muss die Start-Methode vor Beendigung die Ressource abrufen, um festzustellen, ob sie gestartet wurde. Außerdem muss für diese Methode ein ausreichend langer Zeitüberschreitungswert eingestellt werden. Einige Ressourcen, wie zum Beispiel Datenbankdämone, brauchen mehr Zeit zum Starten. Daher benötigt die entsprechende Start-Methode einen höheren Zeitüberschreitungswert.

Die Reaktion von RGM auf einen Fehlschlag der Start-Methode hängt von der Einstellung der Failover_mode-Eigenschaft ab.

Die START_TIMEOUT-Eigenschaft in der Ressourcentyp-Registrierungsdatei stellt den Zeitüberschreitungswert für die Start-Methode einer Ressource ein.

Stop

Diese erforderliche Methode wird auf einem Cluster-Knoten aufgerufen, wenn die Ressourcengruppe mit der Ressource auf diesem Knoten offline gebracht wird. Die Methode deaktiviert die Ressource, wenn sie aktiv ist.

Eine Stop-Methode darf erst dann beendet werden, wenn die von ihr gesteuerte Anwendung vollständig gestoppt wurde, alle Aktivitäten eingestellt und alle Dateideskriptoren geschlossen hat. Andernfalls nimmt RGM an, dass die Ressource gestoppt wurde, während sie in Wirklichkeit noch läuft, was zu Datenfehlern führen kann. Der sicherste Weg zum Vermeiden von Datenfehlern besteht darin, alle Prozesse auf dem lokalen Knoten zu stoppen, die mit der Ressource in Zusammenhang stehen.

Die Stop-Methode muss vor der Beendigung die Ressource abrufen, um festzustellen, ob sie gestoppt wurde. Außerdem muss für diese Methode ein ausreichend langer Zeitüberschreitungswert eingestellt werden. Einige Ressourcen, wie zum Beispiel Datenbankdämone, brauchen mehr Zeit zum Stoppen. Daher benötigt die entsprechende Stopp-Methode einen höheren Zeitüberschreitungswert.

Die Reaktion von RGM auf einen Fehlschlag der Stop-Methode hängt von der Einstellung der Failover_mode-Eigenschaft ab (siehe Tabelle A–2).

Die STOP_TIMEOUT-Eigenschaft in der Ressourcentyp-Registrierungsdatei stellt den Zeitüberschreitungswert für die Stop-Methode einer Ressource ein.

Init

Diese optionale Methode wird aufgerufen, um eine einmalige Initialisierung der Ressource auszuführen, wenn diese in einen verwalteten Zustand versetzt wird — entweder weil die Ressourcengruppe, in der sie sich befindet, aus einem nicht verwalteten in einen verwalteten Zustand versetzt wird, oder weil die Ressource in einer bereits verwalteten Ressourcengruppe erstellt wird. Die Methode wird auf den in der Init_nodes-Ressourceneigenschaft festgelegten Knoten aufgerufen.

Fini

Diese optionale Methode wird aufgerufen, um nach der Ressource zu bereinigen, wenn diese in einen unverwalteten Zustand versetzt wird — entweder, weil die Ressourcengruppe, in der sie sich befindet, in einen unverwalteten Zustand versetzt wird, oder weil die Ressource aus einer verwalteten Ressourcengruppe gelöscht wird. Die Methode wird auf den in der Init_nodes-Ressourceneigenschaft festgelegten Knoten aufgerufen.

Boot

Diese Init ähnliche optionale Methode wird aufgerufen, um die Ressource auf Knoten zu initialisieren, die dem Cluster beitreten, nachdem die Ressourcengruppe mit der Ressource bereits unter RGM-Verwaltung gestellt wurde. Die Methode wird auf den in der Init_nodes-Ressourceneigenschaft festgelegten Knoten aufgerufen. Die Boot-Methode wird aufgerufen, wenn der Knoten dem Cluster beitritt bzw. wenn er als Ergebnis eines Starts oder Neustarts erneut beitritt.

Hinweis –

Ein Fehlschlag der Init-, Fini- oder Boot-Methode bewirkt das Generieren einer Fehlermeldung durch die syslog()-Funktion, hat aber ansonsten keine Auswirkungen auf die RGM-Verwaltung der Ressource.

Verwaltungsunterstützungsmethoden

Verwaltungsaktionen an Ressourcen umfassen das Einstellen und Ändern von Ressourceneigenschaften. Die Validate- und Update-Rückmeldemethoden ermöglichen es einer Ressourcentypimplementierung, diese Verwaltungsaktionen zu nutzen.

Validate

Diese optionale Methode wird aufgerufen, wenn eine Ressource erstellt wird und wenn eine Verwaltungsaktion die Eigenschaften der Ressource bzw. ihrer Ressourcengruppe aktualisiert. Die Methode wird auf denjenigen Clustern aufgerufen, die von der Init_nodes-Eigenschaft des Ressourcentyps angegeben werden. Validate wird aufgerufen, bevor die Erstellung bzw. Aktualisierung angewendet wird. Ein Fehlerbeendigungscode der Methode auf einem Knoten führt zum Abbruch der Erstellung bzw. Aktualisierung.

Validate wird nur dann aufgerufen, wenn Ressourcen- bzw. Ressourcengruppeneigenschaften über eine Verwaltungsaktion geändert werden, und nicht, wenn RGM Eigenschaften einstellt oder wenn ein Monitor die Ressourceneigenschaften Status und Status_msg einstellt.

Update

Diese optionale Methode wird aufgerufen, um eine laufende Ressource über die Änderung ihrer Eigenschaften zu benachrichtigen. Update wird aufgerufen, nachdem eine Verwaltungsaktion erfolgreich die Eigenschaften einer Ressource bzw. deren Gruppe eingestellt hat. Die Methode wird auf denjenigen Knoten aufgerufen, auf denen die Ressource online ist. Die Methode verwendet die API-Zugriffsfunktionen zum Lesen der Eigenschaftswerte, die eine aktive Ressource betreffen könnten, und zum dementsprechenden Anpassen der laufenden Ressource.

Ein Fehlschlag der Update-Methode bewirkt das Generieren einer Fehlermeldung durch die syslog()-Funktion, hat aber ansonsten keine Auswirkungen auf die RGM-Verwaltung der Ressource.

Netzwerkbezogene Rückmeldemethoden

Für Dienste, die Netzwerkadressressourcen verwenden, muss das Starten und Stoppen möglicherweise in einer bestimmten Reihenfolge stattfinden, die in Bezug zur Netzwerkadresskonfiguration steht. Die folgenden optionalen Rückmeldemethoden, Prenet_start und Postnet_stop, ermöglichen es einer Ressourcentypimplementierung, besondere Start- und Schließfunktionen auszuführen, bevor und nachdem eine entsprechende Netzwerkadresse konfiguriert bzw. dekonfiguriert wird.

Prenet_start

Diese optionale Methode wird aufgerufen, um besondere Startaktionen auszuführen, bevor die Netzwerkadressen in derselben Ressourcengruppe konfiguriert werden.

Postnet_stop

Diese optionale Methode wird aufgerufen, um besondere Schließaktionen auszuführen, bevor die Netzwerkadressen in derselben Ressourcengruppe als inaktiv konfiguriert werden.

Monitorsteuerungs-Rückmeldemethoden

Eine Ressourcentypimplementierung kann optional ein Programm enthalten, das die Leistung einer Ressource überwacht, über deren Status berichtet oder bei Ressourcenversagen Aktionen ausführt. Die Monitor_start-, Monitor_stop- und Monitor_check-Methoden unterstützen die Implementierung eines Ressourcen-Monitors in einer Ressourcentypimplementierung.

Monitor_start

Diese optionale Methode wird aufgerufen, um einen Monitor für die Ressource zu starten, nachdem die Ressource gestartet wurde.

Monitor_stop

Diese optionale Methode wird aufgerufen, um einen Ressourcen-Monitor zu stoppen, bevor die Ressource gestoppt wird.

Monitor_check

Diese optionale Methode wird aufgerufen, um die Zuverlässigkeit eines Knotens zu beurteilen, bevor eine Ressourcengruppe auf den Knoten verschoben wird. Die Monitor_check-Methode muss so implementiert werden, dass sie keine Konflikte mit anderen, gleichzeitig laufenden Methoden bewirkt.