Sun Cluster 3.1 Data Services Developer's Guide

Generic Data Service Overview

The generic data service (GDS) is a mechanism for making simple network-aware applications highly available or scalable by plugging them into the Sun Cluster Resource Group Management framework. This mechanism does not require the coding of an agent which is the typical approach for making an application highly available or scalable.

The GDS is a single, precompiled data service. In this approach, the precompiled data service and its components, the callback method (rt_callbacks(1HA)) implementations and the resource type registration file (rt_reg(4)), are not modifiable.

Precompiled Resource Type

The generic data service resource type, SUNW.gds, is included in the SUNWscgds package. The scinstall(1M) utility installs this package during cluster installation. The SUNWscgds package includes the following files:

# pkgchk -v SUNWscgds 


Why Use GDS

The GDS has the following advantages over using either the SunPlex Agent Builder generated source code model (see scdscreate(1HA)) or the standard Sun Cluster administration commands:

Methods of Creating a Service Using GDS

There are 2 methods of creating a service that uses the GDS:

GDS and the SunPlex Agent Builder

Use the SunPlex Agent Builder and select GDS as the type of generated source code. The user input is used to generate a set of driving scripts that configure resources for the given application.

GDS and the Standard Sun Cluster Administration Commands

This method uses the precompiled data service code in SUNWscgds but requires that the system administrator use the standard Sun Cluster administration commands (scrgadm(1M) and scswitch(1M)) to create and configure the resource.

How to Select Which Method to Use to Create a GDS-Based Service

As shown in the procedures Standard Sun Cluster Administration Commands to Create a Highly Available Service Using GDS and Standard Sun Cluster Administration Commands to Create a Scalable Service Using GDS, a significant amount of typing is required to issue the appropriate scrgadm and scswitch commands.

Using the GDS with SunPlex Agent Builder simplifies the process because it generates the driving scripts that issue the scrgadm and scswitch commands for you.

When Is GDS Not Appropriate

While using the GDS has many advantages, there are instances when it is not appropriate to use the GDS. The GDS is not appropriate:

GDS Mandatory Inputs

The following properties must be provided:


The start command, specified on the Start_command property, launches the application. It must be a UNIX command complete with its arguments that can be passed directly to a shell to start the application.


The Port_list property identifies the list of ports that the application listens on. The Port_list property must be specified on the start script created by the SunPlex Agent Builder or on the scrgadm command if you are using the standard Sun Cluster administration commands.

GDS Optional Inputs

The optional inputs to the GDS include:


The default value for this property is Null. This property must be specified if the application needs to bind to one or more specific addresses. If this property is omitted or is specified as Null, the application is assumed to listen on all addresses.

Before creating the GDS resource, a LogicalHostname or SharedAddress resource must already have been configured. See Sun Cluster Data Services Guidefor information on how to configure a LogicalHostname or SharedAddress resource.

To specify a value, specify one or more resource names; each resource name can contain one or more LogicalHostname or one or more SharedAddress. See r_properties(5) for details.


The stop command must stop the application and only return after the application has been completely stopped. It must be a complete UNIX command that can be passed directly to a shell to stop the application.

If the Stop_command is provided, the GDS stop method launches the stop command with 80% of the stop timeout. Regardless of the outcome of launching the stop command, the GDS stop method sends SIGKILL with 15% of the stop timeout. The remaining 5% of the time is reserved for housekeeping overhead.

If the stop command is omitted, the GDS tries to stop the application using the signal specified in Stop_signal.


The probe command periodically checks the health of the given application. It must be a UNIX command complete with its arguments that can be passed directly to a shell to probe the application. The probe command returns with an exit status of 0 if the application is OK.

The exit status of the probe command is used to determine the severity of the failure of the application. This exit status, called probe status, must be an integer between 0 (for success) and 100 (for complete failure). The probe status can also be a special value of 201 which results in immediate failover of the application unless Failover_enabled is set to false. The probe status is used within the GDS probing algorithm (see scds_fm_action(3HA)) to make the decision about restarting the application locally versus failing it over to another node; if the exit status is 201, the application is immediately failed over.

If the probe command is omitted, the GDS provides its own simple probe that connects to the application on the set of IP addresses derived from the Network_resources_used property or the output of scds_get_netaddr_list(3HA). If the connect succeeds, it disconnects immediately. If both connect and disconnect succeed, the application is deemed to be running healthily.

Note –

The probe provided with the GDS is only intended to be a simple substitute for the fully functioning application-specific probe.


This property specifies the start timeout for the start command (see Start_command for additional information). The default for Start_timeout is 300 seconds.


This property specifies the stop timeout for the stop command (see Stop_command for the additional information. The default for Stop_timeout is 300 seconds.


This property specifies the timeout value for the probe command (see Probe_command for additional information. The default for Probe_timeout is 30 seconds.


This property provides control over which processes get monitored through PMF. It denotes the level up to which the forked children processes are monitored. This is similar to the -C argument to the pmfadm(1M) command.

Omitting this property, or setting it to the default value of -1, has the same effect as omitting the -C option on the pmfadm command; that is, all children (and their descendents) will be monitored. See the pmfadm(1M) man page for more details.

Note –

This option can only be specified using the standard Sun Cluster administration commands. This option cannot be specified if you are using the SunPlex Agent Builder.


This boolean extension property controls the failover behavior of the resource. If this extension property is set to true, the application fails over when the number of restarts exceeds the retry_count within the retry_interval number of seconds.

If this extension property is set to false, the application does not restart or fail over to another node when the number of restarts exceed the retry_count within the retry_interval number of seconds.

This extension property can be used to prevent the application resource from initiating a failover of the resource group. The default is true.


The GDS uses the value of this integer extension property to determine the signal used for stopping the application through PMF. See signal(3head) for a list of the integer values that can be specified. The default is 15 (SIGTERM).