Callback Methods

The Sun Cluster framework uses a callback mechanism to provide communication between a data service and the RGM. The framework defines a set of callback methods, including their arguments and return values, and the circumstances under which the RGM calls each method.

You create a data service by coding a set of individual callback methods and implementing each method as a control program callable by the RGM. That is, the data service does not consist of a single executable but rather consists of a number of executable scripts (ksh) or binaries (C), each of which is directly callable by the RGM.

Callback methods are registered with the RGM through the resource type registration (RTR) file . In the RTR file you identify the program for each method you have implemented for the data service. When a system administrator registers the data service on a cluster, the RGM reads the RTR file, which provides, among other information, the identity of the callback programs.

The only required callback methods for a resource type are a start method (Start or Prenet_start), and a stop method (Stop or Postnet_stop).

The callback methods can be grouped into the following categories:

Control and initialization methods
- Start and Stop start and stop resources in a group that is being brought online or offline.
- Init, Fini, Boot execute initialization and termination code on resources.
Administrative support methods
- Validate verifies properties set by administrative action.
- Update updates the property settings of an online resource.
Net-relative methods
- Prenet_start and Postnet_stop do special startup or shutdown actions before network addresses in the same resource group are configured up or after they are configured down.
Monitor control methods
- Monitor_start and Monitor_stop start or stop the monitor for a resource.
- Monitor_check assesses the reliability of a node before a resource group is moved to the node.

See Chapter 4, Resource Management API Reference and the rt_callbacks(1HA) man page for more information on the callback methods. Also see Chapter 5, Sample Data Service and Chapter 8, Sample DSDL Resource Type Implementation for callback methods in sample data services.

Programming Interfaces

For writing data service code, the resource management architecture provides a low-level, or base API, a higher-level library built on top of the base API, and a tool, SunPlex Agent Builder, that automatically generates a data service from basic input that you provide.

RMAPI

The RMAPI (Resource Management API) provides a set of low-level routines that enable a data service to access information about the resources, resource types and resource groups in the system, request a local restart or failover, and set the resource status. You access these functions through the libscha.so library. The RMAPI provides these callback methods both in the form of shell commands and in the form of C functions. See scha_calls(3HA) and Chapter 4, Resource Management API Reference for more information on the RMAPI routines. Also see Chapter 5, Sample Data Service for examples of how to use these routines in sample data service callback methods.

Data Service Development Library (DSDL)

Built on top of the RMAPI is the DSDL, which provides a higher-level integrated framework while retaining the underlying method-callback model of the RGM. The DSDL brings together various facilities for data-service development, including:

libscha.so--the low-level resource management APIs
PMF--the process management facility, which provides a means of monitoring processes and their descendants, and restarting them if they die (see pmfadm(1M) and rpc.pmfd(1M)).
hatimerun--a facility for running programs under a timeout (see hatimerun(1M).

For the majority of applications, the DSDL provides most or all of the functionality you need to build a data service. Note, however, that the DSDL does not replace the low-level API but encapsulates and extends it. In fact, many DSDL functions call the libscha.so functions. Likewise you can directly call libscha.so functions while using the DSDL to code the bulk of your data service. The libdsdev.so library contains the DSDL functions.

See Chapter 6, Data Service Development Library (DSDL) and the scha_calls(3HA) man page for more information about the DSDL.

SunPlex Agent Builder

Agent Builder is a tool that automates the creation of a data service. You input basic information about the target application and the data service to be created.Agent Builder generates a data service, complete with source and executable code (C or Korn shell), customized RTR file, and a Solaris package.

For most applications, you can use Agent Builder to generate a complete data service with only minor manual changes on your part. Applications with more sophisticated requirements, such as adding validation checks for additional properties, might require work that Agent Builder cannot do. However, even in these cases you might be able to use Agent Builder to generate the bulk of the code and manually code the rest. At minimum, you can use Agent Builder to generate the Solaris package for you.

Resource Group Manager Administrative Interface

Sun Cluster provides both a graphical user interface and a set of commands for administering a cluster.

SunPlex Manager

SunPlex Manager is a Web-based tool that enables you to perform the following tasks.

Install a cluster
Administer a cluster
Create and configure resources and resource groups
Configure data services with the Sun Cluster software

See the Sun Cluster 3.1 10/03 Software Installation Guide for instructions on how to install SunPlex Manager and how to use SunPlex Manager to install cluster software. SunPlex Manager provides online help for most unique administrative tasks.

Administrative Commands

The Sun Cluster commands for administering RGM objects are scrgadm(1M), scswitch(1M), and scstat(1M) -g.

The scrgadm command allows viewing, creating, configuring and deleting the resource type, resource group, and resource objects used by the RGM. The command is part of the administrative interface for the cluster, and is not to be used in the same programming context as the application interface described in the rest of this chapter. However, scrgadm is the tool for constructing the cluster configuration in which the API operates. Understanding the administrative interface sets the context for understanding the application interface. Refer to the scrgadm(1M) man page for details on the administrative tasks that can be performed by the command.

The scswitch command switches resource groups online and offline on specified nodes and enables or disables a resource or its monitor. See the scswitch(1M) man page for details on the administrative tasks that the command can perform.

The scstat -g command shows the current dynamic state of all resource groups and resources.


	Callback Methods The Sun Cluster framework uses a callback mechanism to provide communication between a data service and the RGM. The framework defines a set of callback methods, including their arguments and return values, and the circumstances under which the RGM calls each method. You create a data service by coding a set of individual callback methods and implementing each method as a control program callable by the RGM. That is, the data service does not consist of a single executable but rather consists of a number of executable scripts (`ksh`) or binaries (C), each of which is directly callable by the RGM. Callback methods are registered with the RGM through the resource type registration (RTR) file . In the RTR file you identify the program for each method you have implemented for the data service. When a system administrator registers the data service on a cluster, the RGM reads the RTR file, which provides, among other information, the identity of the callback programs. The only required callback methods for a resource type are a start method (`Start` or `Prenet_start`), and a stop method (`Stop` or `Postnet_stop`). The callback methods can be grouped into the following categories: Control and initialization methods `Start` and `Stop` start and stop resources in a group that is being brought online or offline. `Init`, `Fini`, `Boot` execute initialization and termination code on resources. Administrative support methods `Validate` verifies properties set by administrative action. `Update` updates the property settings of an online resource. Net-relative methods `Prenet_start` and `Postnet_stop` do special startup or shutdown actions before network addresses in the same resource group are configured up or after they are configured down. Monitor control methods `Monitor_start` and `Monitor_stop` start or stop the monitor for a resource. `Monitor_check` assesses the reliability of a node before a resource group is moved to the node. See Chapter 4, Resource Management API Reference and the `rt_callbacks`(1HA) man page for more information on the callback methods. Also see Chapter 5, Sample Data Service and Chapter 8, Sample DSDL Resource Type Implementation for callback methods in sample data services. Programming Interfaces For writing data service code, the resource management architecture provides a low-level, or base API, a higher-level library built on top of the base API, and a tool, SunPlex Agent Builder, that automatically generates a data service from basic input that you provide. RMAPI The RMAPI (Resource Management API) provides a set of low-level routines that enable a data service to access information about the resources, resource types and resource groups in the system, request a local restart or failover, and set the resource status. You access these functions through the `libscha.so` library. The RMAPI provides these callback methods both in the form of shell commands and in the form of C functions. See `scha_calls`(3HA) and Chapter 4, Resource Management API Reference for more information on the RMAPI routines. Also see Chapter 5, Sample Data Service for examples of how to use these routines in sample data service callback methods. Data Service Development Library (DSDL) Built on top of the RMAPI is the DSDL, which provides a higher-level integrated framework while retaining the underlying method-callback model of the RGM. The DSDL brings together various facilities for data-service development, including: `libscha.so`--the low-level resource management APIs PMF--the process management facility, which provides a means of monitoring processes and their descendants, and restarting them if they die (see `pmfadm`(1M) and `rpc.pmfd`(1M)). `hatimerun`--a facility for running programs under a timeout (see `hatimerun`(1M). For the majority of applications, the DSDL provides most or all of the functionality you need to build a data service. Note, however, that the DSDL does not replace the low-level API but encapsulates and extends it. In fact, many DSDL functions call the `libscha.so` functions. Likewise you can directly call `libscha.so` functions while using the DSDL to code the bulk of your data service. The `libdsdev.so` library contains the DSDL functions. See Chapter 6, Data Service Development Library (DSDL) and the `scha_calls`(3HA) man page for more information about the DSDL. SunPlex Agent Builder Agent Builder is a tool that automates the creation of a data service. You input basic information about the target application and the data service to be created.Agent Builder generates a data service, complete with source and executable code (C or Korn shell), customized RTR file, and a Solaris package. For most applications, you can use Agent Builder to generate a complete data service with only minor manual changes on your part. Applications with more sophisticated requirements, such as adding validation checks for additional properties, might require work that Agent Builder cannot do. However, even in these cases you might be able to use Agent Builder to generate the bulk of the code and manually code the rest. At minimum, you can use Agent Builder to generate the Solaris package for you. Resource Group Manager Administrative Interface Sun Cluster provides both a graphical user interface and a set of commands for administering a cluster. SunPlex Manager SunPlex Manager is a Web-based tool that enables you to perform the following tasks. Install a cluster Administer a cluster Create and configure resources and resource groups Configure data services with the Sun Cluster software See the Sun Cluster 3.1 10/03 Software Installation Guide for instructions on how to install SunPlex Manager and how to use SunPlex Manager to install cluster software. SunPlex Manager provides online help for most unique administrative tasks. Administrative Commands The Sun Cluster commands for administering RGM objects are `scrgadm`(1M), `scswitch`(1M), and `scstat`(1M) `-g`. The `scrgadm` command allows viewing, creating, configuring and deleting the resource type, resource group, and resource objects used by the RGM. The command is part of the administrative interface for the cluster, and is not to be used in the same programming context as the application interface described in the rest of this chapter. However, `scrgadm` is the tool for constructing the cluster configuration in which the API operates. Understanding the administrative interface sets the context for understanding the application interface. Refer to the `scrgadm`(1M) man page for details on the administrative tasks that can be performed by the command. The `scswitch` command switches resource groups online and offline on specified nodes and enables or disables a resource or its monitor. See the `scswitch`(1M) man page for details on the administrative tasks that the command can perform. The `scstat` `-g` command shows the current dynamic state of all resource groups and resources.