SUNW.gds(5)						     Sun Cluster Miscellaneous						       SUNW.gds(5)

NAME

       SUNW.gds - resource type for making simple network-aware and nonnetwork-aware applications highly available or scalable

DESCRIPTION

       The Generic Data Service (GDS) is a mechanism that enables you to make simple network-aware and nonnetwork-aware applications highly avail-
       able or scalable by plugging them into the Sun Cluster Resource Group Manager (RGM) framework.

       The GDS contains a fully functional Sun Cluster resource type, complete with callback methods (rt_callbacks(1HA)) and a Resource Type  Reg-
       istration (RTR) file (rt_reg(4)).

   Standard Properties
       Network_resources_used (string array)

	   A  list  of logical-hostname or shared-address network resources upon which this resource has a dependency. This list contains all net-
	   work-address resources that appear in the properties Resource_dependencies, Resource_dependencies_weak,  Resource_dependencies_restart,
	   or Resource_dependencies_offline_restart.

	   This  property  is  updated automatically by the RGM, based on the setting of the resource-dependencies properties. You do not set this
	   property directly.  Instead, use the Resource_dependencies property.

	   Category	       Conditional/Optional

	   Default	       The empty list

	   Tunable	       Any time

       Port_list (string array)

	   Specifies a comma-separated list of port numbers on which the application listens. See the r_properties(5) man page.

	   The Port_list property must be specified in the start script that Agent Builder creates or with the clresource command if you are using
	   Sun Cluster administration commands.

	   Note -

	     If Network_aware is set to False, Port_list is not required.

	   Category	       Conditional/Required

	   Default	       No default

	   Tunable	       Any time

       Resource_dependencies (string array)

	   Specifies  a  list  of  resources  upon  which  a  resource depends.  This list includes any logical-hostname or shared-address network
	   resources that are used by a resource. The default value for this property is null.	If the Network_aware property is set to true,  you
	   must set this property to the logical-hostname or shared-address network resources on which the application is listening.

	   Before you create the GDS resource, a LogicalHostname or SharedAddress resource must already be configured.

	   You	can specify one or more resource names. Each network resource can contain one or more logical hostnames. See the clreslogicalhost-
	   name(1CL) and clressharedaddress(1CL) man pages for more information.

	   You	can  specify  an  alternate  kind  of  dependency  by  using  the  Resource_dependencies_weak,	Resource_dependencies_restart,	or
	   Resource_dependencies_offline_restart  property instead of the Resource_dependencies property.  For more information, see the r_proper-
	   ties(5) man page.

	   Category	       Optional

	   Default	       The empty list

	   Tunable	       Any time

       Start_timeout (integer)

	   Specifies the timeout value, in seconds, for the start command.

	   Category	       Optional

	   Default	       300 seconds

	   Tunable	       Any time

       Stop_timeout (integer)

	   Specifies the timeout value, in seconds, for the stop command.

	   Category	       Optional

	   Default	       300 seconds

	   Tunable	       Any time

       Validate_timeout (integer)

	   Specifies the timeout value, in seconds, for the validate command.

	   Category	       Optional

	   Default	       300 seconds

	   Tunable	       Any time

   Extension Properties
       Child_mon_level (integer)

	   Provides control over the processes that are monitored through the Process Monitor Facility (PMF). This property denotes the  level	to
	   which  the forked children processes are monitored. Omitting this property or setting this property to the default value is the same as
	   omitting the -C option for pmfadm(1M): all children (and their descendents) are monitored.

	   Category	       Optional

	   Default	       -1

	   Tunable	       At creation

       Failover_enabled (boolean)

	   Allows the resource to fail over. If this property is set to False, failover of the resource is disabled. You can use this property	to
	   prevent the application resource from initiating a failover of the resource group.

	   Note -

	     Use  the  Failover_mode  property	instead  of the Failover_enabled extension property because Failover_mode better controls failover
	     behavior. For more information, see the descriptions of the LOG_ONLY and RESTART_ONLY values for Failover_mode in r_properties(5).

	   Category	       Optional

	   Default	       True

	   Tunable	       When disabled

       Log_level (enum)

	   Specifies the level, or type, of diagnostic messages that are logged by GDS. You can specify None, Info, or Err for this property. When
	   you	specify  None,	diagnostic  messages are not logged by GDS. When you specify Info, both information and error messages are logged.
	   When you specify Err, only error messages are logged.

	   Category	       Optional

	   Default	       Info

	   Tunable	       Any time

       Network_aware (boolean)

	   This property specifies whether an application uses the network.

	   Category	       Optional

	   Default	       True

	   Tunable	       At creation

       Probe_command (string)

	   Specifies the command that periodically checks the health of a network-aware or nonnetwork-aware application. This command  must  be  a
	   complete command line 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 running correctly.

	   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, is an integer between 0 (for success) and 100 (for complete failure). The probe status can also be 201, which causes the
	   application to fail over unless Failover_enabled is set to False.

	   The probe status is used within the GDS probing algorithm to determine whether to restart the application locally or to fail  over  the
	   application to another node or zone. If the probe command is omitted, the GDS provides its own simple probe that connects to the appli-
	   cation on the network resource. If the connect succeeds, the GDS disconnects immediately.  If both connect and disconnect succeed,  the
	   application is deemed to be running correctly.

	   The	GDS  does  not	provide  "default"  probing behavior for nonnetwork-aware applications. However, a nonnetwork-aware application is
	   started under the PMF, which monitors the application and restarts the application if it fails. The pmfadm(1M) man page  contains  more
	   information.

	   Category	       Optional

	   Default	       Null

	   Tunable	       When disabled

       Probe_timeout (integer)

	   Specifies the timeout value, in seconds, for the probe command.

	   Category	       Optional

	   Default	       30 seconds

	   Tunable	       Any time

       Start_command (string)

	   Specifies  the command that starts the application. This command must be a complete command line that can be passed directly to a shell
	   to start the application.

	   The start command, or one of its forked children, is expected to be a long-running program or daemon which actually provides  the  ser-
	   vice  to  clients.	The  start  command  process  tree  is	monitored  by  the  Process  Monitor Facility (PMF) as described under the
	   Child_mon_level extension property. If the monitored processes exit, they are restarted according to the settings  of  the  Retry_count
	   and	Retry_interval resource properties. If the retry count is exceeded, an attempt is made to relocate the resource group to a differ-
	   ent node or zone.

	   The exit status that is returned by the start command or its children is ignored.

	   Category	       Required

	   Default	       No default

	   Tunable	       When disabled

       Stop_command (string)

	   Specifies the command that stops the application. This command must be a complete command line that can be passed directly to  a  shell
	   to stop the application. If this property is omitted, or if the stop command exits nonzero, the GDS stops the application by using sig-
	   nals.

	   Category	       Optional

	   Default	       Null

	   Tunable	       When disabled

       Stop_signal (integer)

	   Specifies the signal that stops the application. The values of this property are the same as those defined in signal(3HEAD).

	   Category	       Optional

	   Default	       15

	   Tunable	       When disabled

       Validate_command (string)

	   Specifies the absolute path to the command that validates the application. If you do not provide an absolute path, the  application	is
	   not validated.

	   The	exit  status  of the validate command is used to determine whether the creation or update of the GDS resource should be permitted.
	   Before creating or updating the resource, the specified validate command is executed on each node of the  node  list  of  the  resource
	   group  that	contains  the resource. If the validate command exits nonzero, the requested resource creation or update is not permitted.
	   Any output that is written to stdout or stderr by the validate command will be passed back to the user who  issued  the  administrative
	   command to create or update the resource. Such output can be used to explain why the resource validation failed.

	   The validate command is also executed when bringing the gds resource online, before executing the Start_command extension property.	If
	   the validate command exits nonzero, it is treated as a start failure.

	   The validate command is also executed before performing the GIVEOVER option of the scha_control command to relocate the resource  group
	   to  a  new  node  or zone. If the command exits nonzero, the giveover is blocked and the resource group remains mastered on its current
	   node or zone.

	   Category	       Optional

	   Default	       Null

	   Tunable	       When disabled

EXAMPLES

       The following examples show how to use GDS to make an application named app highly available. You can also use Sun  Cluster  Agent  Builder
       (scdsbuilder(1HA)) to create scripts that contain these commands.

   Basic Example
       This  example  shows  how  to  register the SUNW.gds resource type, create a resource group for the application, create the LogicalHostname
       resource for the logical host name hhead, create the network-aware  application	resource,  manage  the	resource  group,  enable  all  its
       resources, and bring its resources online.

       At  this  point, the application is running, highly available, and monitored by the simple probe that is provided by GDS. You can now check
       the status of the application.

	 # clresourcetype register SUNW.gds
	 # clresourcegroup create rg1
	 # clreslogicalhostname create -g rg1 -h hhead
	 # clresource create -g rg1 -t SUNW.gds 
	 -p Start_command="/usr/local/app/bin/start" 
	 -p Port_list="1234/tcp" -p Network_aware=True -p Resource_dependencies=hhead app-rs
	 # clresourcegroup online -M rg1
	 # clresourcegroup status +

   Complex Example
       This example shows how to register the SUNW.gds resource type, create a resource group for  the	application,  create  the  LogicalHostname
       resource  for  the  logical  host  name	hhead, create the network-aware application resource, log error messages only, manage the resource
       group, enable all the resources, and bring the resources online.

       At this point, the application is running, highly available, and monitored by the fault monitor that is specified  by  Probe_command.   You
       can now check the status of the application.

	 # clresourcetype register SUNW.gds
	 # clresourcegroup create rg1
	 # clreslogicalhostname create -g rg1 -h hhead
	 # clresource create -g rg1 -t SUNW.gds 
	 -p Start_command="/usr/local/app/bin/start" 
	 -p Stop_command="/usr/local/app/bin/stop" 
	 -p Validate_command="/usr/local/app/bin/config" 
	 -p Probe_command="/usr/local/app/bin/probe" 
	 -p stop_signal=9 -p failover_enabled=FALSE 
	 -p Start_timeout=120 -p Stop_timeout=180 
	 -p Port_list="1234/tcp" -p Probe_timeout=60 
	 -p Network_aware=True -p Validate_timeout=120 -p Log_level=Err -p Resource_dependencies=hhead app-rs
	 # clresourcegroup online -M rg1
	 # clresourcegroup status +

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWscgds 		   |
       +-----------------------------+-----------------------------+

SEE ALSO

       clreslogicalhostname(1CL),  clresource(1CL),  clresourcegroup(1CL),  clresourcetype(1CL), clressharedaddress(1CL), rt_callbacks(1HA), scds-
       builder(1HA), scha_control(1HA), scha_resource_get(1HA), hatimerun(1M),	pmfadm(1M),  signal(3HEAD),  rt_reg(4),  attributes(5),  r_proper-
       ties(5), scalable_service(5)

SunOS 5.9							    24 Sep 2007 						       SUNW.gds(5)