Sun and OracleChannel SunHow to BuyLog InEnglish

Sun Cluster 3.1 10/03 Data Services Developer's Guide
  Search only this book
Search Help
View this book in:
Contained Within
Find More Documentation
Featured Support Resources
 Download this book in PDF (1414 KB)

Chapter 10 Generic Data Services

This chapter provides information on the generic data service (GDS) and shows you how to create a service that uses the GDS using either the SunPlex Agent Builder or the standard Sun Cluster administration commands.

Overview of GDS

The 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. You cannot modify the precompiled data service and its components, the callback method (rt_callbacks(1HA)) implementations and the resource type registration file (rt_reg(4)).

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 

/opt/SUNWscgds 
/opt/SUNWscgds/bin 
/opt/SUNWscgds/bin/gds_monitor_check 
/opt/SUNWscgds/bin/gds_monitor_start 
/opt/SUNWscgds/bin/gds_monitor_stop 
/opt/SUNWscgds/bin/gds_probe 
/opt/SUNWscgds/bin/gds_svc_start 
/opt/SUNWscgds/bin/gds_svc_stop 
/opt/SUNWscgds/bin/gds_update 
/opt/SUNWscgds/bin/gds_validate 
/opt/SUNWscgds/etc 
/opt/SUNWscgds/etc/SUNW.gds

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:

  • The GDS is easy to use.

  • The GDS and its methods are precompiled and are therefore not modifiable.

  • The SunPlex Agent Builder can be used to generate driving scripts for your application and these scripts are packaged in a Solaris-installable package that can be reused across multiple clusters.

Ways to Create a Service That Uses GDS

There are two ways to create a service that uses the GDS:

  • Using the SunPlex Agent Builder

  • Using the standard Sun Cluster administration commands

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.

Selecting the Method to Use to Create a GDS-Based Service

As shown in the procedures How to Use 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:

  • When more control is required than is available using the precompiled resource type. such as when you need to add extension properties or change the defaults.

  • When the source code needs to be modified to add special functions.

  • When you want to use multiple process trees.

  • When you want to use non-network-aware applications.

Required Properties for GDS

The following properties must be provided:

  • Start_command (extension property)

  • Port_list

Start_command Extension Property

The start command, which you specify in the Start_command extension 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.

Port_list Property

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.

Optional Properties for GDS

Optional GDS properties include:

  • Network_resources_used

  • Stop_command (extension property)

  • Probe_command(extension property)

  • Start_timeout

  • Stop_timeout

  • Probe_timeout (extension property)

  • Child_mon_level (extension property only used with the standard administration commands)

  • Failover_enabled (extension property)

  • Stop_signal (extension property)

Network_resources_used Property

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 the Sun Cluster 3.1 Data Service Planning and Administration Guide for information about 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.

Stop_command Property

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.

Probe_command Property

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.

Start_timeout Property

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

Stop_timeout Property

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

Probe_timeout Property

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

Child_mon_level Property

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.

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.

Failover_enabled Property

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.

Stop_signal Property

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

Using the SunPlex Agent Builder to Create a Service Using GDS

You can use the SunPlex Agent Builder to create the service that uses the GDS. The SunPlex Agent Builder is described in more detail in Chapter 9, SunPlex Agent Builder.

Create a Service Using GDS in the SunPlex Agent Builder

Creating a Service Using GDS in the Agent Builder

  1. Start the SunPlex Agent Builder.


    # /usr/cluster/bin/scdsbuilder

  2. The SunPlex Agent Builder panel appears.

    Dialog box titled SunPlex Agent Builder that shows the main Agent Builder screen

  3. Enter the Vendor Name.

  4. Enter the Application Name.

    Note –

    The combination of Vendor and Application Name may not contain more than nine characters. It is used as the name of the package for the driving scripts.

  5. Go to the working directory.

    You can use the Browse pulldown to select the directory rather than typing the path.

  6. Select whether the data service is scalable or failover.

    You do not need to select Network Aware since that is the default when creating the GDS.

  7. Select GDS.

  8. Click the Create button to create the driving scripts.

  9. The SunPlex Agent Builder panel displays the results of the creation of the service. The Create button is grayed out and you can now use the Next button.

    Dialog box that shows the create screen after information has been entered
Configuring the Driving Scripts

After creating the driving scripts, you need to use the SunPlex Agent Builder to configure the new service.

  1. Click the Next button and the configuration panel appears.

  2. Either enter the location of the Start command or use the browse button to locate the Start command.

  3. (Optional) Enter the Stop command or use the browse button to locate the Stop command.

  4. (Optional) Enter the Probe command or use the browse button to locate the Probe command.

  5. (Optional) Specify the timeout values for the Start, Stop, and Probe commands.

  6. Click Configure to start the configuration of the driving scripts.

    Note –

    The package name will consist of a concatenation of the Vendor Name and Application Name.

    A package for driving scripts will be created and placed in: 


    <working-dir>/<vendor_name><application>/pkg
    For example, /export/wdir/NETapp/pkg

  7. Install the completed package on all nodes of the cluster. 


    # cd /export/wdir/NETapp/pkg 
# pkgadd -d . NETapp

  8. The following files will be installed during the pkgadd: 


    /opt/NETapp 
/opt/NETapp/README.app 
/opt/NETapp/man 
/opt/NETapp/man/man1m 
/opt/NETapp/man/man1m/removeapp.1m 
/opt/NETapp/man/man1m/startapp.1m 
/opt/NETapp/man/man1m/stopapp.1m 
/opt/NETapp/man/man1m/app_config.1m 
/opt/NETapp/util 
/opt/NETapp/util/removeapp 
/opt/NETapp/util/startapp 
/opt/NETapp/util/stopapp 
/opt/NETapp/util/app_config

    Note –

    The man pages and script names will correspond to the Application Name you entered above preceded by the script name; for example, startapp.

    To view the man pages, you need to specify the path to the man page. For example, to view the startapp man pages, use:


    # man -M /opt/NETapp/man startapp

  9. On one node of the cluster, configure the resources and start the application. 


    # /opt/NETapp/util/startapp -h <logichostname> -p <port and protocol list>

    The arguments to the start script will vary according to the type of resource: failover or scalable. Check the customized man page or run the start script without any argument to get a usage statement.


    # /opt/NETapp/util/startapp 
 The resource name of LogicalHostname or SharedAddress must be specified. 
 For failover services: 
 Usage: startapp -h <logical host name> 
          -p <port and protocol list> 
          [-n <ipmpgroup/adapter list>] 
 For scalable services: 
 Usage: startapp  
          -h <shared address name> 
          -p <port and protocol list> 
          [-l <load balancing policy>]  
          [-n <ipmpgroup/adapter list>] 
          [-w <load balancing weights>]

Output From SunPlex Agent Builder

The SunPlex Agent Builder generates three driving scripts and a configuration file based on input you provide during package creation. The configuration file specify the names of the resource group and resource type.

The driving scripts are:

  • Start script: Used to configure the resources and start the application under RGM control.

  • Stop script: Used to stop the application and take down resources and resource groups.

  • Remove script: Used to remove the resources and resource groups created by the start script.

These driving scripts have the same interface and behavior as the utility scripts generated by the SunPlex Agent Builder for non-GDS-based agents. The scripts are packaged in a Solaris-installable package that can be reused across multiple clusters.

You can customize the configuration file to provide your own names for resource groups or other parameters that are normally given as inputs to the scrgadm command. If you do not customize the scripts, the SunPlex Agent Builder provides reasonable defaults for the scrgadm parameters.

Using the Standard Sun Cluster Administration Commands to Create a Service Using GDS

In this section we describe how these parameters can actually be input to the GDS. The GDS is used and administered using the existing Sun Cluster administration commands such as scrgadm and scswitch.

Then there is no need to enter the lower level administration commands shown in this section if the driving scripts provide adequate functionality. However, you can do so if you need to have finer control over the GDS-based resource. These are the commands actually executed by the driving scripts.

How to Use Sun Cluster Administration Commands to Create a Highly Available Service Using GDS

  1. Register the resource type SUNW.gds 


    # scrgadm -a -t SUNW.gds

  2. Create the resource group containing the LogicalHostname resource and the failover service itself.


    # scrgadm -a -g haapp_rg

  3. Create the resource for the LogicalHostname resource.


    # scrgadm -a -L -g haapp_rs -l hhead

  4. Create the resource for the failover service itself.


    # scrgadm -a -j haapp_rs -g haapp_rg -t SUNW.gds \
         -y Scalable=false -y Start_timeout=120 \
         -y Stop_timeout=120 -x Probe_timeout=120 \
         -y Port_list="2222/tcp" \
         -x Start_command="/export/ha/appctl/start" \
         -x Stop_command="/export/ha/appctl/stop" \    
         -x Probe_command="/export/app/bin/probe" \
         -x Child_mon_level=0 -y Network_resources_used=hhead \
         -x Failover_enabled=true -x Stop_signal=9

  5. Bring the resource group haapp_rg online.


    # scswitch -Z -g haapp_rg
Standard Sun Cluster Administration Commands to Create a Scalable Service Using GDS

  1. Register the resource type SUNW.gds. 


    # scrgadm -a -t SUNW.gds

  2. Create the resource group for the SharedAddress resource.


    # scrgadm -a -g sa_rg

  3. Create the SharedAddress resource on sa_rg.


    # scrgadm -a -S -g sa_rg -l hhead

  4. Create the resource group for the scalable service.


    # scrgadm -a -g app_rg -y Maximum_primaries=2 \
      -y Desired_primaries=2 -y RG_dependencies=sa_rg

  5. Create the resource group for the scalable service itself. 


    # scrgadm -a -j app_rs -g app_rg -t SUNW.gds \
       -y Scalable=true -y Start_timeout=120 \ 
       -y Stop_timeout=120 -x Probe_timeout=120 \
       -y Port_list="2222/tcp" \
       -x Start_command="/export/app/bin/start" \
       -x Stop_command="/export/app/bin/stop" \
       -x Probe_command="/export/app/bin/probe" \
       -x Child_mon_level=0 -y Network_resource_used=hhead \
       -x Failover_enabled=true -x Stop_signal=9

  6. Bring the resource group containing the network resources online.


     # scswitch -Z -g sa_rg

  7. Bring the resource group app_rg online.


    # scswitch -Z -g app_rg

Command-Line Interface to the SunPlex Agent Builder

The SunPlex Agent Builder has a command-line interface that has equivalent functionality to the GUI interface. This interface consists of the commands scdscreate(1HA) and scdsconfig(1HA). The following section performs the same function as the GUI-based procedure Creating a Service That Uses GDS With the Command-Line Version of Agent Builder but uses the non-GUI interface.

Creating a Service That Uses GDS With the Command-Line Version of Agent Builder

  1. Create the service.

    For a failover service, use:


    # scdscreate -g -V NET -T app -d /export/wdir

    For a scalable service, use:


    # scdscreate -g -s -V NET -T app -d /export/wdir
    Note –

    The –d parameters are optional. If it is not specified, the working directory defaults to the current directory.

  2. Configure the service.


    # scdsconfig -s "/export/app/bin/start' -t "/export/app/bin/stop" \
-m "/export/app/bin/probe" -d /export/wdir

    Note –

    Only the start command is required. All other parameters are optional.

  3. Install the completed package on all nodes of the cluster. 


    # cd /export/wdir/NETapp/pkg 
# pkgadd -d . NETapp

  4. The following files will be installed during the pkgadd: 


    /opt/NETapp 
/opt/NETapp/README.app 
/opt/NETapp/man 
/opt/NETapp/man/man1m 
/opt/NETapp/man/man1m/removeapp.1m 
/opt/NETapp/man/man1m/startapp.1m 
/opt/NETapp/man/man1m/stopapp.1m 
/opt/NETapp/man/man1m/app_config.1m 
/opt/NETapp/util 
/opt/NETapp/util/removeapp 
/opt/NETapp/util/startapp 
/opt/NETapp/util/stopapp 
/opt/NETapp/util/app_config

    Note –

    The man pages and script names will correspond to the Application Name you entered above preceded by the script name; for example, startapp.

    To view the man pages, you need to specify the path to the man page. For example, to view the startapp man pages, use:


    # man -M /opt/NETapp/man startapp

  5. On one node of the cluster, configure the resources and start the application. 


    # /opt/NETapp/util/startapp -h <logichostname> -p <port and protocol list>

    The arguments to the start script will vary according to the type of resource: failover or scalable. Check the customized man page or run the start script without any argument to get a usage statement.


    # /opt/NETapp/util/startapp 
 The resource name of LogicalHostname or SharedAddress must be specified. 
 For failover services: 
 Usage: startapp -h <logical host name> 
          -p <port and protocol list> 
          [-n <ipmpgroup/adapter list>] 
 For scalable services: 
 Usage: startapp  
          -h <shared address name> 
          -p <port and protocol list> 
          [-l <load balancing policy>]  
          [-n <ipmpgroup/adapter list>] 
          [-w <load balancing weights>]