Sun Cluster 3.1 Data Services Developer's Guide

Chapter 6 Data Service Development Library (DSDL)

This chapter provides an overview of the application programming interfaces constituting the Data Service Development Library, or DSDL. The DSDL is implemented the library and is included in the Sun Cluster package.

The following information is in this chapter.

DSDL Overview

The DSDL API is layered on top of the RMAPI. As such, it does not supersede the RMAPI but rather encapsulates and extends the RMAPI functionality. The DSDL simplifies data service development by providing predetermined solutions to specific Sun Cluster integration issues. Consequently, you can devote the majority of development time to the high availability and scalability issues intrinsic to your application, and avoid spending a large amount of time on integrating the application startup, shutdown, and monitor procedures with Sun Cluster.

Managing Configuration Properties

All callback methods require access to the configuration properties. The DSDL supports access to properties by:

The scds_initialize function, which must be called at the beginning of each callback method, does the following.

Note –

For the Validate method, scds_initialize parses the property values that are passed on the command line, obviating the need to write a parse function for Validate.

The scds_initialize function also initializes the logging environment and validates fault monitor probe settings.

The DSDL provides sets of functions to retrieve resource, resource type, and resource group properties as well as commonly-used extension properties. These functions standardize access to properties by using the following conventions.

Starting and Stopping a Data Service

A Start method is expected to perform the actions required to start a data service on a cluster node. Typically, this includes retrieving the resource properties, locating application-specific executables and configuration files, and launching the application with the appropriate command-line arguments.

The scds_initialize function retrieves the resource configuration. The Start method can use property convenience functions to retrieve values for specific properties, such as Confdir_list, that identify the configuration directories and files for the application to launch.

A Start method can call scds_pmf_start to launch an application under control of the Process Monitor Facility (PMF). PMF enables you to specify the level of monitoring to apply to the process and provides the ability to restart the process in case of failure. See The xfnts_start Method for an example of a Start method implemented with the DSDL.

A Stop method must be idempotent such that it exits with success even if it is called on a node when the application is not running. If the Stop method fails, the resource being stopped is set to the STOP_FAILED state, which can lead to a hard reboot of the cluster.

To avoid putting the resource in STOP_FAILED state the Stop method must make every effort to stop the resource. The scds_pmf_stop function provides a phased attempt to stop the resource. It first attempts to stop the resource using SIGTERM signal, and if this fails, uses a SIGKILL signal. See scds_pmf_stop(3HA) for details.

Implementing a Fault Monitor

The DSDL absorbs much of the complexity of implementing a fault monitor by providing a predetermined model. A Monitor_start method launches the fault monitor, under the control of PMF, when the resource starts on a node. The fault monitor runs in loop as long as the resource is running on the node. The high-level logic of a DSDL fault monitor is as follows.

Accessing Network Address Information

The DSDL provides convenience functions to return network address information for resources and resource groups. For example, the scds_get_netaddr_list retrieves the network-address resources used by a resource, enabling a fault monitor to probe the application.

The DSDL also provides a set of functions for TCP-based monitoring. Typically, these functions establish a simple socket connection to a service, read and write data to the service, and then disconnect from the service. The result of the probe can be sent to the DSDL scds_fm_action function to determine the action to take.

See The svc_probe Function for an example of TCP-based fault monitoring.

Debugging the Resource Type Implementation

The DSDL has built-in features to help you debug your data service.

The DSDL utility scds_syslog_debug() provides a basic framework for adding debugging statements to the resource type implementation. The debugging level (a number between 1-9) can be dynamically set per resource type implementation per cluster node. A file named /var/cluster/rgm/rt/<rtname>/loglevel containing only an integer between 1-9 is read by all resource type callback methods. The DSDL routine scds_initialize() reads this file and sets the debug level internally to the specified level. The default debug level 0, specifies that the data service log no debugging messages.

The scds_syslog_debug() function uses the facility returned by the scha_cluster_getlogfacility(3HA) function at a priority of LOG_DEBUG. You can configure these debug messages in /etc/syslog.conf.

You can turn some debugging messages into informational messages for regular operation of the resource type (perhaps at LOG_INFO priority) using the scds_syslog utility. If you look at the sample DSDL application in Chapter 8, Sample DSDL Resource Type Implementation you will notice that it makes liberal use of scds_syslog_debug and scds_syslog functions.

Enabling Highly Available Local File Systems

The HAStoragePlus resource type can be used to make a local file system highly available within a Sun Cluster environment. The local file system partitions must reside on global disk groups with affinity switchovers enabled and the Sun Cluster environment must be configured for failover. This enables the user to make any file system on multi-host disks accessible from any host directly connected to those multi-host disks. Using a highly available local file system is strongly recommended for some I/O intensive data services, and configuring the HAStoragePlus resource type has been added to the Registration and Configuration procedures in the Sun Cluster Data Services Guide.