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

Handling Property Updates

The sample data service implements Validate and Update methods to handle the updating of properties by a cluster administrator.

How the Validate Method Works

The RGM calls the Validate method when a resource is created and when administrative action updates the properties of the resource or its containing group. The RGM calls Validate before the creation or update is applied, and a failure exit code from the method on any node causes the creation or update to be canceled.

The RGM calls Validate only when resource or resource group properties are changed by the cluster administrator, not when the RGM sets properties or when a monitor sets the resource properties Status and Status_msg.


Note - The Monitor_check method also explicitly calls the Validate method whenever the PROBE method attempts to fail over the data service to a new node.


What the Validate Method Does

The RGM calls Validate with additional arguments to those that are passed to other methods, including the properties and values that are being updated. Therefore, this method in the sample data service must implement a different parse_args() function to handle the additional arguments.

The Validate method in the sample data service verifies a single property, the Confdir extension property. This property points to the DNS configuration directory, which is critical to the successful operation of DNS.


Note - Because the configuration directory cannot be changed while DNS is running, the Confdir property is declared in the RTR file as TUNABLE = AT_CREATION. Therefore, the Validate method is never called to verify the Confdir property as the result of an update, but only when the data service resource is being created.


If Confdir is one of the properties that the RGM passes to Validate, the parse_args() function retrieves and saves its value. Validate verifies that the directory pointed to by the new value of Confdir is accessible and that the named.conf file exists in that directory and contains data.

If the parse_args() function cannot retrieve the value of Confdir from the command-line arguments that are passed by the RGM, Validate still attempts to validate the Confdir property. Validate uses scha_resource_get() to obtain the value of Confdir from the static configuration. Validate performs the same checks to verify that the configuration directory is accessible and contains a named.conf file that is not empty.

If Validate exits with failure, the update or creation of all properties, not just Confdir, fails.

Validate Method Parsing Function

Because the RGM passes the Validate method a different set of arguments than the other callback methods, Validate requires a different function for parsing arguments than the other methods. See the rt_callbacks(1HA) man page for more information about the arguments that are passed to Validate and the other callback methods. The following code sample shows the Validate parse_args() function.

#########################################################################
# Parse Validate arguments.
#
function parse_args # [args...]
{

   typeset opt
   while getopts 'cur:x:g:R:T:G:X:' 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
                  ;;
         X)
                  # Per-node extension property setting. The format of the
                  # option argument is "propertyname{nodeid}=propertyvalue".
                  # For example, there might be two -X options with the following
                  # arguments:
                  #    myprop{1}=myvalue
                  #    myprop{2}=othervalue
                  # representing the setting of property 'myprop' on nodes 1
                  # and 2.
                  # In most cases, the -X arguments can be ignored.  Instead
                  # use the -x argument to get the property setting for the
                  # local node.
                  ;;
         r)
                  # The method is not accessing any system defined
                  # properties so this is a no-op
                  ;;
         g)
                  # The method is not accessing any resource group
                  # properties, so this is a no-op
                  ;;
         c)
                  # Indicates the Validate method is being called while
                  # creating the resource, so this flag is a no-op.
                  ;;
         u)
                  # Indicates the updating of a property when the
                  # resource already exists. If the update is to the
                  # Confdir property then Confdir should appear in the
                  # command-line arguments. If it does not, the method must
                  # look for it specifically using scha_resource_get.
                  UPDATE_PROPERTY=1
                  ;;
         x)
                  # Extension property list. Separate the property and
                  # value pairs using "=" as the separator.
                  PROPERTY=`echo $OPTARG | awk -F= '{print $1}'`
                  VAL=`echo $OPTARG | awk -F= '{print $2}'`
                  # If the Confdir extension property is found on the
                  # command line, note its value.
                  if [ $PROPERTY == "Confdir" ]; then
                           CONFDIR=$VAL
                           CONFDIR_FOUND=1
                  fi
                  ;;
         *)
                  logger -p ${SYSLOG_FACILITY}.err \
                  -t [$SYSLOG_TAG] \
                  "ERROR: Option $OPTARG unknown"
                  exit 1
                  ;;
         esac
   done
}

As with the parse_args() function for other methods, this function provides a flag (R) to capture the resource name, (G) to capture the resource group name, and (T) to capture the resource type that is passed by the RGM.

The r flag (which indicates a system-defined property), g flag (which indicates a resource group property), and the c flag (which indicates that the validation is occurring during creation of the resource) are ignored. They are ignored because this method is being called to validate an extension property when the resource is being updated.

The u flag sets the value of the UPDATE_PROPERTY shell variable to 1 (TRUE). The x flag captures the names and values of the properties that are being updated. If Confdir is one of the properties being updated, its value is placed in the CONFDIR shell variable, and the variable CONFDIR_FOUND is set to 1 (TRUE).

Validating Confdir

In its MAIN function, Validate first sets the CONFDIR variable to the empty string and UPDATE_PROPERTY and CONFDIR_FOUND to 0.

CONFDIR=""
UPDATE_PROPERTY=0
CONFDIR_FOUND=0

Validate calls parse_args() to parse the arguments that are passed by the RGM.

parse_args “$@”

Validate checks if Validate is being called as the result of an update of properties. Validate also checks if the Confdir extension property was on the command line. Validate verifies that the Confdir property has a value, and if not, exits with failure status and an error message.

if ( (( $UPDATE_PROPERTY == 1 )) &&  (( CONFDIR_FOUND == 0 )) ); then
         config_info=`scha_resource_get -O Extension -R $RESOURCE_NAME \
            -G $RESOURCEGROUP_NAME Confdir`
         CONFDIR=`echo $config_info | awk '{print $2}'`
fi

# Verify that the Confdir property has a value. If not there is a failure
# and exit with status 1
if [[ -z $CONFDIR ]]; then
         logger -p ${SYSLOG_FACILITY}.err \
            "${ARGV0} Validate method for resource "$RESOURCE_NAME " failed"
         exit 1
fi

Note - Specifically, the preceding code checks if Validate is being called as the result of an update ($UPDATE_PROPERTY == 1) and if the property was not found on the command line (CONFDIR_FOUND == 0). In this case, the code retrieves the existing value of Confdir by using scha_resource_get(). If Confdir was found on the command line (CONFDIR_FOUND == 1), the value of CONFDIR comes from the parse_args() function, not from scha_resource_get().


The Validate method uses the value of CONFDIR to verify that the directory is accessible. If the directory is not accessible, Validate logs an error message and exits with error status.

# Check if $CONFDIR is accessible.
if [ ! -d $CONFDIR ]; then
   logger -p ${SYSLOG_FACILITY}.err \
         -t [$SYSLOG_TAG] \
         "${ARGV0} Directory $CONFDIR missing or not mounted"
   exit 1
fi

Before validating the update of the Confdir property, Validate performs a final check to verify that the named.conf file is present. If the file is not present, the method logs an error message and exits with error status.

# Check that the named.conf file is present in the Confdir directory
if [ ! -s $CONFDIR/named.conf ]; then
         logger -p ${SYSLOG_FACILITY}.err \
            -t [$SYSLOG_TAG] \
            "${ARGV0} File $CONFDIR/named.conf is missing or empty"
         exit 1
fi

If the final check is passed, Validate logs a message that indicates success and exits with success status.

# Log a message indicating that the Validate method was successful.
logger -p ${SYSLOG_FACILITY}.err \
   -t [$SYSLOG_TAG] \
   "${ARGV0} Validate method for resource "$RESOURCE_NAME \
   " completed successfully"

exit 0

Validate Exit Status

If Validate exits with success (0), Confdir is created with the new value. If Validate exits with failure (1), Confdir and any other properties are not created and a message that indicates the reason is generated.

How the Update Method Works

The RGM runs the Update method to notify a running resource that its properties have been changed. The RGM runs Update after the cluster administrator succeeds in setting properties of a resource or its group. This method is called on nodes where the resource is online.

What the Update Method Does

The Update method does not update properties. The RGM updates properties. The Update method notifies running processes that an update has occurred. The only process in the sample data service that is affected by a property update is the fault monitor. Consequently, the fault monitor process is the process that the Update method stops and restarts.

The Update method must verify that the fault monitor is running and then kill it by using the pmfadm command. The method obtains the location of the probe program that implements the fault monitor, and restarts it by using the pmfadm command.

Stopping the Monitor With Update

The Update method uses pmfadm -q to verify that the monitor is running, and if so, kills it with pmfadm -s TERM. If the monitor is successfully terminated, a message to that effect is sent to the cluster administrator. If the monitor cannot be stopped, Update exits with failure status and sends an error message to the cluster administrator.

if pmfadm -q $RESOURCE_NAME.monitor; then

# Kill the monitor that is running already
pmfadm -s $PMF_TAG TERM
    if [ $? -ne 0 ]; then
       logger -p ${SYSLOG_FACILITY}.err \
              -t [$SYSLOG_TAG] \
                 "${ARGV0} Could not stop the monitor"
       exit 1
    else
    # could successfully stop DNS. Log a message.
       logger -p ${SYSLOG_FACILITY}.err \
              -t [$RESOURCETYPE_NAME,$RESOURCEGROUP_NAME,$RESOURCE_NAME] \
                 "Monitor for HA-DNS successfully stopped"
    fi

Restarting the Monitor

To restart the monitor, the Update method must locate the script that implements the probe program. The probe program is located in the base directory for the data service, which is pointed to by the RT_basedir property. Update retrieves the value of RT_basedir and stores it in the RT_BASEDIR variable, as follows.

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

Update uses the value of RT_BASEDIR with pmfadm to restart the dns_probe program. If successful, Update exits with success and sends a message to that effect to the cluster administrator. If pmfadm cannot start the probe program, Update exits with failure status and logs an error message.

Update Exit Status

Update method failure causes the resource to be put into an “update failed” state. This state has no effect on RGM management of the resource, but indicates the failure of the update action to administration tools through the syslog() function.