JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Oracle Solaris Cluster Data Services Developer's Guide     Oracle Solaris Cluster 4.1
search filter icon
search icon

Document Information

Preface

1.  Overview of Resource Management

2.  Developing a Data Service

3.  Resource Management API Reference

4.  Modifying a Resource Type

5.  Sample Data Service

Overview of the Sample Data Service

Defining the Resource Type Registration File

Overview of the RTR File

Resource Type Properties in the Sample RTR File

Resource Properties in the Sample RTR File

System-Defined Properties in the RTR File

Extension Properties in the RTR File

Providing Common Functionality to All Methods

Identifying the Command Interpreter and Exporting the Path

Declaring the PMF_TAG and SYSLOG_TAG Variables

Parsing the Function Arguments

Generating Error Messages

Obtaining Property Information

Controlling the Data Service

How the Start Method Works

What the Start Method Does

Verifying the Configuration

Starting the Application

Start Exit Status

How the Stop Method Works

What the Stop Method Does

Stopping the Application

Stop Exit Status

Defining a Fault Monitor

How the Probe Program Works

What the Probe Program Does

Obtaining Property Values

Checking the Reliability of the Service

Comparing Restart With Failover

Restarting the Data Service

Probe Exit Status

How the Monitor_start Method Works

What the Monitor_start Method Does

Starting the Probe

How the Monitor_stop Method Works

What the Monitor_stop Method Does

Stopping the Monitor

Monitor_stop Exit Status

How the Monitor_check Method Works

Handling Property Updates

How the Validate Method Works

What the Validate Method Does

Validate Method Parsing Function

Validating Confdir

Validate Exit Status

How the Update Method Works

What the Update Method Does

Stopping the Monitor With Update

Restarting the Monitor

Update Exit Status

6.  Data Service Development Library

7.  Designing Resource Types

8.  Sample DSDL Resource Type Implementation

9.  Oracle Solaris Cluster Agent Builder

10.  Generic Data Service

11.  DSDL API Functions

12.  Cluster Reconfiguration Notification Protocol

13.  Security for Data Services

A.  Sample Data Service Code Listings

B.  DSDL Sample Resource Type Code Listings

C.  Requirements for Non-Cluster-Aware Applications

D.  Document Type Definitions for the CRNP

E.  CrnpClient.java Application

Index

Providing Common Functionality to All Methods

This section describes the following functionality that is used in all callback methods of the sample data service:

Identifying the Command Interpreter and Exporting the Path

The first line of a shell script must identify the command interpreter. Each method script in the sample data service identifies the command interpreter, as follows:

#!/bin/ksh

All method scripts in the sample application export the path to the Oracle Solaris Cluster binaries and libraries rather than relying on the user's PATH settings.

#######################################################################
# MAIN
#######################################################################

export PATH=/bin:/usr/bin:/usr/cluster/bin:/usr/sbin:/usr/proc/bin:$PATH

Declaring the PMF_TAG and SYSLOG_TAG Variables

All the method scripts, except Validate, use the pmfadm command to start or to stop either the data service or the monitor, and to pass the name of the resource. Each script defines a variable, PMF_TAG, that can be passed to the pmfadm command to identify either the data service or the monitor.

Likewise, each method script uses the logger command to log messages in the system log. Each script defines a variable, SYSLOG_TAG, that can be passed to logger with the -t option to identify the resource type, resource name, and resource group of the resource for which the message is being logged.

All methods define SYSLOG_TAG in the same way, as shown in the following sample code. The dns_probe, dns_svc_start, dns_svc_stop, and dns_monitor_check methods define PMF_TAG as follows (the use of pmfadm and logger is from the dns_svc_stop method).

#########################################################################
# MAIN
#########################################################################

PMF_TAG=$RESOURCE_NAME.named

SYSLOG_TAG=$RESOURCETYPE_NAME,$RESOURCEGROUP_NAME,$RESOURCE_NAME

   # Send a SIGTERM signal to the data service and wait for 80% of the
   # total timeout value.
   pmfadm -s $PMF_TAG.named -w $SMOOTH_TIMEOUT TERM
   if [ $? -ne 0 ]; then
      logger -p ${SYSLOG_FACILITY}.info \
          -t [$SYSLOG_TAG] \
          “${ARGV0} Failed to stop HA-DNS with SIGTERM; Retry with \
           SIGKILL”

The dns_monitor_start, dns_monitor_stop, and dns_update methods define PMF_TAG as follows (the use of pmfadm is from the dns_monitor_stop method):

#####################################################################
# MAIN
#####################################################################

PMF_TAG=$RESOURCE_NAME.monitor
SYSLOG_TAG=$RESOURCETYPE_NAME,$RESOURCEGROUP_NAME,$RESOURCE_NAME
...
# See if the monitor is running, and if so, kill it. 
if pmfadm -q $PMF_TAG.monitor; then
   pmfadm -s $PMF_TAG.monitor KILL

Parsing the Function Arguments

The RGM runs all of the callback methods, except Validate, as follows:

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

The method name is the path name of the program that implements the callback method. A data service specifies the path name for each method in the RTR file. These path names are relative to the directory that is specified by the RT_basedir property, also in the RTR file. For example, in the sample data service's RTR file, the base directory and method names are specified as follows:

RT_basedir=/opt/ORCLsample/bin;
Start = dns_svc_start;
Stop =  dns_svc_stop;
...

All callback method arguments are passed as flagged values. The -R argument indicates the name of the resource instance. The -T argument indicates the type of the resource. The -G argument indicates the group into which the resource is configured. See the rt_callbacks(1HA) man page for more information about callback methods.


Note - The Validate method is called with additional arguments, that is, the property values of the resource and resource group on which it is called. See Handling Property Updates for more information.


Each callback method needs a function to parse the arguments that the function is passed. Because the callbacks are all passed the same arguments, the data service provides a single parse function that is used in all the callbacks in the application.

The following sample shows the parse_args() function that is used for the callback methods in the sample application.

#########################################################################
# Parse program arguments.
#
function parse_args # [args ...]
{
      typeset opt

      while getopts 'R:G:T:' opt
      do
             case "$opt" in
             R)
                  # Name of the DNS resource.
                  RESOURCE_NAME=$OPTARG
                  ;;
             G)
                  # Name of the resource group in which the resource is
                  # configured.
                  RESOURCEGROUP_NAME=$OPTARG
                  ;;
             T)
                  # Name of the resource type.
                  RESOURCETYPE_NAME=$OPTARG
                  ;;
             *)
                  logger -p ${SYSLOG_FACILITY}.err \
                  -t [$RESOURCETYPE_NAME,$RESOURCEGROUP_NAME,$RESOURCE_NAME] \
                  "ERROR: Option $OPTARG unknown"
                  exit 1
                      ;;
             esac
    done
}

Note - Although the PROBE method in the sample application is user defined (not an Oracle Solaris Cluster callback method), it is called with the same arguments as the callback methods. Therefore, this method contains a parse function that is identical to the one that is used by the other callback methods.


The parse function is called in MAIN as:

parse_args “$@”

Generating Error Messages

Callback methods should use the syslog() function to output error messages to end users. All callback methods in the sample data service use the scha_cluster_get command to retrieve the number of the syslog() function that is used for the cluster log, as follows:

SYSLOG_FACILITY=`scha_cluster_get -O SYSLOG_FACILITY`

The value is stored in a shell variable, SYSLOG_FACILITY, and can be used as the facility of the logger command to log messages in the cluster log. For example, the Start method in the sample data service retrieves the syslog() function and logs a message that the data service has been started, as follows:

SYSLOG_FACILITY=`scha_cluster_get -O SYSLOG_FACILITY`
...
if [ $? -eq 0 ]; then
   logger -p ${SYSLOG_FACILITY}.err \
         -t [$SYSLOG_TAG] \
         "${ARGV0} HA-DNS successfully started"
fi

See the scha_cluster_get(1HA) man page for more information.

Obtaining Property Information

Most callback methods need to obtain information about resource and resource type properties of the data service. The API provides the scha_resource_get() function for this purpose.

Both system-defined properties and extension properties are available. System-defined properties are predefined. You define extension properties in the RTR file.

When you use scha_resource_get() to obtain the value of a system-defined property, you specify the name of the property with the -O option. The command returns only the value of the property. For example, in the sample data service, the Monitor_start method needs to locate the probe program so it can start it. The probe program is located in the base directory for the data service, which is pointed to by the RT_basedir property. The Monitor_start method retrieves the value of RT_basedir and places it in the RT_BASEDIR variable, as follows:

RT_BASEDIR=`scha_resource_get -O RT_basedir -R $RESOURCE_NAME -G \
$RESOURCEGROUP_NAME`

For extension properties, you must use the -O option to specify that the property is an extension property. You must also supply the name of the property as the last argument. For extension properties, the command returns both the type and value of the property. For example, in the sample data service, the probe program retrieves the type and value of the Probe_timeout extension property, and uses the awk command to put the value only in the PROBE_TIMEOUT shell variable, as follows:

probe_timeout_info=`scha_resource_get -O Extension \
-R $RESOURCE_NAME -G $RESOURCEGROUP_NAME Probe_timeout`
PROBE_TIMEOUT=`echo $probe_timeout_info | awk '{print $2}'`