Handling Property Updates
The sample data service implements Validate and Update methods to handle updating of properties by a cluster administrator.
Validate Method
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 group properties are changed through administrative action, 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 the data service over to a new node.
Validate Overview
The RGM calls Validate with additional arguments to those passed to other methods, including the properties and values 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 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 the RGM passes to Validate, the parse_args() function retrieves and saves its value. Validate then 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 some data.
If the parse_args() function cannot retrieve the value of Confdir from the command-line arguments 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. Then it performs the same checks to verify that the configuration directory is accessible and contains a non-empty named.conf file.
If Validate exits with failure, the update or creation of all properties, not just Confdir, fails.
Validate Method Parsing Function
The RGM passes the Validate method a different set of parameters than the other callback methods so Validate requires a different function for parsing arguments than the other methods. See the rt_callbacks(1HA) man page for more information on the parameters passed to Validate and the other callback methods. The following shows the Validate parse_args() function.
#########################################################################
# Parse Validate arguments.
#
function parse_args # [args...]
{
typeset opt
while getopts 'cur:x:g:R:T:G:' 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
;;
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 passed by the RGM.
The r flag (indicating a system-defined property), g flag (indicating a resource group property), and the c flag (indicating that the validation is occurring during creation of the resource) 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 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 then calls parse_args() to parse the arguments passed by the RGM.
parse_args “$@” |
Validate then checks if Validate is being called as the result of an update of properties and if the Confdir extension property was on the command line. Validate then 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 which case it retrieves the existing value of Confdir 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 then uses the value of CONFDIR to verify that the directory is accessible. If it 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 it is not, 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 indicating 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 indicating why is sent to the cluster administrator.
Update Method
The RGM calls the Update method to notify a running resource that its properties have been changed. The RGM invokes Update after an administrative action succeeds in setting properties of a resource or its group. This method is called on nodes where the resource is online.
Update Overview
The Update method doesn't update properties—that is done by the RGM. Rather, it notifies running processes that an update has occurred. The only process in the sample data service affected by a property update is the fault monitor, so it is this process the Update method stops and restarts.
The Update method must verify the fault monitor is running and then kill it using pmfadm. The method obtains the location of the probe program that implements the fault monitor, then restarts it using pmfadm again.
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 administrative user. If the monitor cannot be stopped, Update exits with failure status and sends an error message to the administrative user.
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 resides 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 then 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 administrative user. If pmfadm cannot launch 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 facility.
- © 2010, Oracle Corporation and/or its affiliates