Sun Cluster Data Services Developer's Guide for Solaris OS

Defining the Resource Type Registration File

The resource type registration (RTR) file in this example defines the static configuration of the DNS resource type. Resources of this type inherit the properties defined in the RTR file.

The information in the RTR file is read by the RGM when the cluster administrator registers the HA-DNS data service.

RTR File Overview

The RTR file follows a well-defined format. Resource type properties are defined first in the file, system-defined resource properties are defined next, and extension properties are defined last. See the rt_reg(4) man page and Setting Resource and Resource Type Properties for more information.

This section describes the specific properties in the sample RTR file. It provides listings of different parts of the file. For a complete listing of the contents of the sample RTR file, see Resource Type Registration File Listing.

Resource Type Properties in the Sample RTR File

The sample RTR file begins with comments followed by resource type properties that define the HA-DNS configuration, as shown in the following listing.

#
# Copyright (c) 1998-2004 by Sun Microsystems, Inc.
# All rights reserved.
#
# Registration information for Domain Name Service (DNS)
#

#pragma ident   “@(#)SUNW.sample   1.1   00/05/24 SMI”

RESOURCE_TYPE = “sample”;
VENDOR_ID = SUNW;
RT_DESCRIPTION = “Domain Name Service on Sun Cluster”;

RT_VERSION =”1.0”; 
API_VERSION = 2;    
FAILOVER = TRUE;

RT_BASEDIR=/opt/SUNWsample/bin;
PKGLIST = SUNWsample;

START         =   dns_svc_start;
STOP          =   dns_svc_stop;

VALIDATE      =   dns_validate;
UPDATE        =   dns_update;

MONITOR_START =   dns_monitor_start;
MONITOR_STOP  =   dns_monitor_stop;
MONITOR_CHECK =   dns_monitor_check;

Tip –

You must declare the Resource_type property as the first entry in the RTR file. Otherwise, registration of the resource type will fail.

Note –

The RGM treats property names as case insensitive. The convention for properties in Sun-supplied RTR files, with the exception of method names, is uppercase for the first letter of the name and lowercase for the rest of the name. Method names—as well as property attributes—contain all uppercase letters.

Some information about these properties follows.

The resource type name can be specified by the Resource_type property alone (sample) or using the Vendor_id as a prefix with a “.” separating it from the resource type (SUNW.sample).

If you use Vendor_id, make it the stock symbol for the company defining the resource type. The resource type name must be unique in the cluster.
The Rt_version property identifies the version of the sample data service as specified by the vendor.
The API_version property identifies the Sun Cluster version. For example, API_version = 2, indicates that the data service runs under Sun Cluster version 3.0.
Failover = TRUE indicates that the data service cannot run in a resource group that can be online on multiple nodes at once.
RT_basedir points to /opt/SUNWsample/bin as the directory path to complete relative paths, such as callback method paths.
Start, Stop, Validate, and so on provide the paths to the respective callback method programs invoked by the RGM. These paths are relative to the directory specified by RT_basedir.
Pkglist identifies SUNWsample as the package that contains the sample data service installation.

Resource type properties not specified in this RTR file, such as Single_instance, Init_nodes, and Installed_nodes, get their default value. See Table A–1 for a complete list of the resource type properties, including their default values.

The cluster administrator cannot change the values specified for resource type properties in the RTR file.

Resource Properties in the Sample RTR File

By convention, you declare resource properties following the resource type properties in the RTR file. Resource properties include system-defined properties provided by Sun Cluster and extension properties you define. For either type you can specify a number of property attributes supplied by Sun Cluster, such as minimum, maximum, and default values.

System-Defined Properties in the RTR File

The following listing shows the system-defined properties in the sample RTR file.

# A list of bracketed resource property declarations follows the 
# resource-type declarations. The property-name declaration must be
# the first attribute after the open curly bracket of each entry.

# The <method>_timeout properties set the value in seconds after which 
# the RGM concludes invocation of the method has failed. 

# The MIN value for all method timeouts is set to 60 seconds. This 
# prevents administrators from setting shorter timeouts, which do not 
# improve switchover/failover performance, and can lead to undesired 
# RGM actions (false failovers, node reboot, or moving the resource group 
# to ERROR_STOP_FAILED state, requiring operator intervention). Setting
# too-short method timeouts leads to a *decrease* in overall availability 
# of the data service.
{  
   PROPERTY = Start_timeout; 
   MIN=60; 
   DEFAULT=300;
}

{
   PROPERTY = Stop_timeout; 
   MIN=60; 
   DEFAULT=300;
}
{
        PROPERTY = Validate_timeout;
        MIN=60;
        DEFAULT=300;
}
{
        PROPERTY = Update_timeout;
        MIN=60;
        DEFAULT=300;
}
{
        PROPERTY = Monitor_Start_timeout;
        MIN=60;
        DEFAULT=300;
}
{
        PROPERTY = Monitor_Stop_timeout;
        MIN=60;
        DEFAULT=300;
}
{
        PROPERTY = Thorough_Probe_Interval;
        MIN=1;
        MAX=3600;
        DEFAULT=60;
        TUNABLE = ANYTIME;
}

# The number of retries to be done within a certain period before concluding 
# that the application cannot be successfully started on this node.
{
        PROPERTY = Retry_Count;
        MIN=0;
        MAX=10;
        DEFAULT=2;
        TUNABLE = ANYTIME; 
}

# Set Retry_Interval as a multiple of 60 since it is converted from seconds
# to minutes, rounding up. For example, a value of 50 (seconds)
# is converted to 1 minute. Use this property to time the number of 
# retries (Retry_Count).
{
        PROPERTY = Retry_Interval;
        MIN=60;
        MAX=3600;
        DEFAULT=300;
        TUNABLE = ANYTIME;
}

{
        PROPERTY = Network_resources_used;
        TUNABLE = AT_CREATION;
        DEFAULT = ““;
}

Although Sun Cluster provides the system-defined properties, you can set different default values using resource property attributes. See Resource Property Attributes for a complete list of attributes available for applying to resource properties.

Note the following about the system-defined resource properties in the sample RTR file:

Sun Cluster provides a minimum value (1 second) and a default value (3600 seconds) for all timeouts. The sample RTR file changes the minimum 60 and changes the default to 300 seconds. A cluster administrator can accept this default value or change the value of the timeout to something else, (60 or greater). Sun Cluster has no maximum allowable value.
The properties Thorough_Probe_Interval, Retry_count, and Retry_interval, have the TUNABLE attribute set to ANYTIME. This settings means the cluster administrator can change the value of these properties, even when the data service is running. These properties are used by the fault monitor implemented by the sample data service. The sample data service implements an Update method to stop and restart the fault monitor when these or other resource properties are changed by administrative action. See Update Method.
Resource properties are classified as
- required—the cluster administrator must specify a value when creating a resource;
- optional—if the administrator does not specify a value, the system supplies a default value.
- conditional—the RGM creates the property only if it is declared in the RTR file.
The fault monitor of the sample data service makes use of the Thorough_probe_interval, Retry_count, Retry_interval, and Network_resources_used conditional properties, so the developer needed to declare them in the RTR file. See the r_properties(5) man page or Resource Properties for information about how properties are classified.

Extension Properties in the RTR File

At the end of the sample RTR file are extension properties, as shown in the following listing

# Extension Properties

# The cluster administrator must set the value of this property to point to the 
# directory that contains the configuration files used by the application. 
# For this application, DNS, specify the path of the DNS configuration file on 
# PXFS (typically named.conf).
{
   PROPERTY = Confdir;
   EXTENSION;
   STRING;
   TUNABLE = AT_CREATION;
   DESCRIPTION = “The Configuration Directory Path”;
}

# Time out value in seconds before declaring the probe as failed.
{
        PROPERTY = Probe_timeout;
        EXTENSION;
        INT;
        DEFAULT = 120;
        TUNABLE = ANYTIME;
        DESCRIPTION = “Time out value for the probe (seconds)”;
}

The sample RTR file defines two extension properties, Confdir and Probe_timeout. Confdir specifies the path to the DNS configuration directory. This directory contains the in.named file, which DNS requires to operate successfully. The sample data service's Start and Validate methods use this property to verify that the configuration directory and the in.named file are accessible before starting DNS.

When the data service is configured, the Validate method verifies that the new directory is accessible.

The sample data services's PROBE method is not a Sun Cluster callback method but a user-defined method. Therefore, Sun Cluster doesn't provide a Probe_timeout property for it. The developer has defined an extension property in the RTR file to allow a cluster administrator to configure a Probe_timeout value.