Skip Navigation Links
Exit Print View
| Oracle Solaris Cluster Data Services Developer's Guide Oracle Solaris Cluster 4.1

Search Scope:

- This Document
- Entire Library

## 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.

Copyright © 2000, 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |