Sun Cluster Data Services Developer's Guide for Solaris OS

Chapter 10 Generic Data Services

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

This chapter covers the following topics:

Generic Data Services Concepts

The GDS is a mechanism for making simple network-aware and nonnetwork-aware applications highly available or scalable by plugging them into the Sun Cluster Resource Group Management (RGM) framework. This mechanism does not require you to code a data service, which you typically must do to make an application highly available or scalable.

You can configure a GDS-based data service to run in non-global zones provided that your associated application is also configured to run in non-global zones.

The GDS is a single, precompiled data service. You cannot modify the precompiled data service and its components, the callback method (rt_callbacks) implementations, and the resource type registration file (rt_reg).

This section covers the following topics:

Precompiled Resource Type

The generic data service resource type SUNW.gds is included in the SUNWscgds package. The scinstall utility installs this package during cluster installation. See the scinstall(1M) man page. 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

Advantages and Disadvantages of Using the GDS

Using the GDS has the following advantages over using either the Agent Builder source code (see the scdscreate(1HA) man page) or Sun Cluster administration commands:

While using the GDS has many advantages, the GDS is not the mechanism to use in these instances:

Ways to Create a Service That Uses the GDS

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

GDS and Agent Builder

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

GDS and Sun Cluster Administration Commands

This method uses the precompiled data service code in SUNWscgds. However, the cluster administrator must use Sun Cluster administration commands to create and configure the resource. See the clresource(1CL) man page.

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

A significant amount of typing is required to issue Sun Cluster commands. For example, see How to Use Sun Cluster Administration Commands to Create a Highly Available Service That Uses the GDS and How to Use Sun Cluster Administration Commands to Create a Scalable Service That Uses the GDS.

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

How the GDS Logs Events

The GDS enables you to log relevant information that is passed from the GDS to the scripts that the GDS starts. This information includes the status of the start, probe, validate, and stop methods as well as property variables. You can use this information to diagnose problems or errors in your scripts, or apply it to other purposes.

You use the Log_level property that is described in Log_level Property to specify the level, or type, of messages that the GDS is to log. You can specify NONE, INFO, or ERR.

GDS Log Files

The following two GDS log files are placed in the directory /var/cluster/logs/DS/resource-group-name/resource-name:

The following example shows the types of information that start_stop_log.txt contains:

06/12/2006 12:38:05 phys-node-1 START-INFO> Start succeeded. [/home/brianx/sc/start_cmd]
06/12/2006 12:42:11 phys-node-1 STOP-INFO> Successfully stopped the application

The following example shows the types of information that probe_log.txt contains:

06/12/2006 12:38:15 phys-node-1 PROBE-INFO> The GDS monitor (gds_probe) has been started
06/12/2006 12:39:15 phys-node-1 PROBE-INFO> The probe result is 0
06/12/2006 12:40:15 phys-node-1 PROBE-INFO> The probe result is 0
06/12/2006 12:41:15 phys-node-1 PROBE-INFO> The probe result is 0

Required GDS Properties

If your application is network aware, you must provide both the Start_command extension property and the Port_list property. If your application is nonnetwork aware, you must provide only the Start_command extension property.

Start_command Property

The start command, which you specify with the Start_command extension property, starts the application. This command must be a UNIX command with 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 on which the application listens. 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.

Optional GDS Properties

Optional GDS properties include both system-defined properties and extension properties. System-defined properties are a standard set of properties that are provided by Sun Cluster. Properties that are defined in the RTR file are called extension properties.

Here are optional GDS properties:

Child_mon_level Property


Note –

If you use Sun Cluster administration commands, you can use the Child_mon_level property. If you use Agent Builder, you cannot use this property.


This property provides control over the processes that are monitored through the Process Monitor Facility (PMF). This property denotes the level up to which the forked children processes are monitored. This property works like the -C argument to the pmfadm command. See the pmfadm(1M) man page.

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 are monitored.

Failover_enabled Property

This 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 property is set to FALSE, the application does not restart or fail over to another node or zone when the number of restarts exceeds the Retry_count within the Retry_interval number of seconds.

You can use this property to prevent the application resource from initiating a failover of the resource group. The default value for this property is TRUE.


Note –

In future, use the Failover_mode property in place of the Failover_enabled extension property as Failover_mode better controls failover behavior. For more information, see the descriptions of the LOG_ONLY and RESTART_ONLY values for Failover_mode in the r_properties(5) man page.


Log_level Property

This property specifies the level, or type, of diagnostic messages that are logged by the GDS. You can specify NONE, INFO, or ERR for this property. When you specify NONE, diagnostic messages are not logged by the GDS. When you specify INFO, only informational messages are logged. When you specify ERR, only error messages are logged. By default, the GDS does not log diagnostic messages (NONE).

Network_resources_used Property

This property specifies a list of logical host name or shared address network resources that are used by a resource. The default value for this property is null. You must specify this property if the application needs to bind to one or more specific addresses. If you omit this property or you specify Null, the application listens on all addresses.

Before you create the GDS resource, a LogicalHostname or SharedAddress resource must already be configured. See the Sun Cluster Data Services Planning and Administration Guide for Solaris OS 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 resources or one or more SharedAddress resources. See the r_properties(5) man page for details.

Probe_command Property

This property specifies the probe command that periodically checks the health of a given application. This command must be a UNIX command with 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 running correctly.

The exit status of the probe command is used to determine the severity of the application's failure. This exit status, called the 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 causes the application to immediately fail over unless Failover_enabled is set to FALSE. The GDS probing algorithm uses the probe status to determine whether to restart the application locally or fail it over. See the scds_fm_action(3HA) man page for more information. 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. This probe connects to the application on the set of IP addresses that is derived from the Network_resources_used property or from the output of the scds_get_netaddr_list() function. See the scds_get_netaddr_list(3HA) man page for more information. If the connect succeeds, the connect disconnects immediately. If both the connect and disconnect succeed, the application is deemed to be running well.


Note –

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


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.

Start_timeout Property

This property specifies the start timeout for the start command. See Start_command Property for additional information. The default for Start_timeout is 300 seconds.

Stop_command Property

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

If the Stop_command extension property is provided, the GDS stop method starts the stop command with 80 percent of the stop timeout. Regardless of the outcome of starting the stop command, the GDS stop method sends SIGKILL with 15 percent of the stop timeout. The remaining 5 percent of the time is reserved for housekeeping overhead.

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

Stop_signal Property

This property specifies a value that identifies the signal to stop an application through the PMF. See the signal(3HEAD) man page for a list of the integer values that you can specify. The default value is 15 (SIGTERM).

Stop_timeout Property

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

Validate_command Property

This property specifies the absolute path to a command to invoke to validate the application. If you do not provide an absolute path, the application is not validated.

Validate_timeout Property

This property specifies the timeout for the validate command. See Validate_command Property for additional information. The default for Validate_timeout is 300 seconds.

Using Agent Builder to Create a Service That Uses the GDS

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

Creating and Configuring GDS-Based Scripts

ProcedureHow to Start Agent Builder and Create the Scripts

  1. Become superuser or assume a role that provides solaris.cluster.modify RBAC authorization.

  2. Start Agent Builder.


    # /usr/cluster/bin/scdsbuilder
    
  3. The Agent Builder Create screen appears.

    Dialog box titled Sun Cluster Agent Builder that shows
the main Agent Builder Create screen
  4. Type the vendor name.

  5. Type the application name.


    Note –

    Starting with the Solaris 9 OS, the combination of vendor name and application name can exceed nine characters. This combination is used as the name of the package for the scripts.


  6. Go to the working directory.

    You can use the Browse drop-down menu to select the directory rather than typing the path.

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

    You do not need to select Network Aware because that setting is the default when you create the GDS.

  8. Select GDS.

  9. (Optional) Change the RT version from the default value that is shown.


    Note –

    You cannot use the following characters in the RT Version field: space, tab, slash (/), backslash (\), asterisk (*), question mark (?), comma (,), semicolon (;), left square bracket ([), or right square bracket (]).


  10. Click Create.

    Agent Builder creates the scripts. The results are displayed in the Output Log area.

    Dialog box that shows the Create screen after information
has been entered

    Note that the Create button is grayed out. You can now configure the scripts.

  11. Click Next.

    The Configure screen appears.

    Dialog box that shows the Configure screen

ProcedureHow to Configure the Scripts

After creating the scripts, you need to configure the new service.

  1. Type the location of the start command, or click Browse to locate the start command.

    You can specify property variables. Property variables are described in Using Property Variables.

  2. (Optional) Type the location of the stop command, or click Browse to locate the stop command.

    You can specify property variables. Property variables are described in Using Property Variables.

  3. (Optional) Type the location of the validate command, or click Browse to locate the validate command.

    You can specify property variables. Property variables are described in Using Property Variables.

  4. (Optional) Type the location of the probe command, or click Browse to locate the probe command.

    You can specify property variables. Property variables are described in Using Property Variables.

  5. (Optional) Specify new timeout values for the start, stop, validate, and probe commands.

  6. Click Configure.

    Agent Builder configures the scripts.


    Note –

    Agent Builder concatenates the vendor name and the application name to create the package name.


    A package for scripts is created and placed in the following directory:

    working-dir/vendor-name-application/pkg
    

    For example, /export/wdir/NETapp/pkg.

  7. On each node of the cluster, become superuser or assume a role that provides solaris.cluster.modify RBAC authorization.

  8. On each node of the cluster, install the completed package.


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

    The following files are installed by 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 correspond to the application name that you typed previously on the Create screen, preceded by the script name (for example, startapp).


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


    # /opt/NETapp/util/startapp -h logicalhostname -p port-and-protocol-list
    

    The arguments to the startapp script vary according to the type of resource: failover or scalable.


    Note –

    To determine the command line that you need to type, check the customized man page, or run the startapp script without any arguments to display a usage statement.

    To view the man pages, you need to specify the path to the man page. For example, to view the startapp(1M) man page, type:


    # man -M /opt/NETapp/man startapp
    

    To display a usage statement, type:


    # /opt/NETapp/util/startapp
     The resource name of LogicalHostname or SharedAddress must be
     specified. For failover services:
     Usage: startapp -h logicalhostname
              -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 Agent Builder

Agent Builder generates three scripts and a configuration file based on input that you provide when you create the package. The configuration file specifies the names of the resource group and the resource type.

The scripts are as follows:

These scripts have the same interface and behavior as the utility scripts that are generated by Agent Builder for non-GDS-based data services. The scripts are put in a Solaris package that you can reuse across multiple clusters.

You can customize the configuration file to provide your own names for resource groups or other arguments that are normally given as arguments to the scrgadm and scswitch commands. If you do not customize the scripts, Agent Builder provides default values for these arguments.

Using Sun Cluster Administration Commands to Create a Service That Uses the GDS

This section describes how to input arguments to the GDS. You use the existing Sun Cluster administration commands, such as clresourcetype, clresourcegroup, and clresource to maintain and administer the GDS.

If the scripts provide adequate functionality, you do not need to use the lower-level administration commands that are shown in this section. However, you can use the lower-level administration commands if you need to have finer control over the GDS-based resource. These commands are executed by the scripts.

ProcedureHow to Use Sun Cluster Administration Commands to Create a Highly Available Service That Uses the GDS

  1. Become superuser or assume a role that provides solaris.cluster.modify RBAC authorization.

  2. Register the resource type SUNW.gds.


    # clresourcetype register SUNW.gds
    
  3. Create the resource group that contains the LogicalHostname resource and the failover service itself.


    # clresourcegroup create haapp_rg
    
  4. Create the resource for the LogicalHostname resource.


    # clreslogicalhostname create -g haapp_rg hhead
    
  5. Create the resource for the failover service itself.


    # clresource create -g haapp_rg -t SUNW.gds
            -p Validate_command="/export/app/bin/configtest" \
            -p Scalable=false -p Start_timeout=120 \
            -p Stop_timeout=120 -p Probe_timeout=120 \
            -p Port_list="2222/tcp" \
            -p Start_command="/export/ha/appctl/start" \
            -p Stop_command="/export/ha/appctl/stop" \
            -p Probe_command="/export/app/bin/probe" \
            -p Child_mon_level=0 -p Network_resources_used=hhead \
            -p Failover_enabled=TRUE -p Stop_signal=9 haapp_rs
    
  6. Bring the resource group haapp_rg online in a managed state.


    # clresourcegroup online -M haapp_rg
    

ProcedureHow to Use Sun Cluster Administration Commands to Create a Scalable Service That Uses the GDS

  1. Become superuser or assume a role that provides solaris.cluster.modify RBAC authorization.

  2. Register the resource type SUNW.gds.


    # clresourcetype register SUNW.gds
    
  3. Create the resource group for the SharedAddress resource.


    # clresourcegroup create sa_rg
    
  4. Create the SharedAddress resource hhead in resource group sa_rg.


    # clressharedaddress create -g sa_rg hhead
    
  5. Create the resource group for the scalable service.


    # clresourcegroup create -S -p RG_dependencies=sa_reg app_rg
    
  6. Create the resource for the scalable service.


    # clresource create -g app_rg -t SUNW.gds
            -p Validate_command="/export/app/bin/configtest" \
            -p Scalable=TRUE -p Start_timeout=120 \
            -p Stop_timeout=120 -p Probe_timeout=120 \
            -p Port_list="2222/tcp" \
            -p Start_command="/export/app/bin/start" \
            -p Stop_command="/export/app/bin/stop" \
            -p Probe_command="/export/app/bin/probe" \
            -p Child_mon_level=0 -p Network_resource_used=hhead \
            -p Failover_enabled=TRUE -p Stop_signal=9 app_rs
    
  7. Bring the resource group that contains the network resources online.


    # clresourcegroup online sa_reg
    
  8. Bring the resource group app_rg online in a managed state.


    # clresourcegroup online -M app_reg
    

Command-Line Interface for Agent Builder

Agent Builder incorporates a command-line interface that provides the same functionality that the GUI provides. This interface consists of the commands scdscreate and scdsconfig. See the scdscreate(1HA) and scdsconfig(1HA) man pages.

ProcedureHow to Use the Command-Line Version of Agent Builder to Create a Service That Uses GDS

This section describes how to use the command-line interface to perform the same set of steps shown in Using Agent Builder to Create a Service That Uses the GDS.

  1. Become superuser or assume a role that provides solaris.cluster.modify RBAC authorization.

  2. Create the service.

    • For a failover service, type:


      # scdscreate -g -V NET -T app -d /export/wdir
      
    • For a scalable service, type:


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

    Note –

    The -d argument is optional. If you do not specify this argument, the current directory becomes the working directory.


  3. Configure the service.


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

    You can specify property variables. Property variables are described in Using Property Variables.


    Note –

    Only the start command (scdsconfig -s) is required. All other options and arguments are optional.


  4. On each node of the cluster, install the completed package.


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

    The following files are installed by 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 correspond to the application name that you typed previously on the Create screen, preceded by the script name (for example, startapp).


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


    # /opt/NETapp/util/startapp -h logicalhostname -p port-and-protocol-list
    

    The arguments to the startapp script vary according to the type of resource: failover or scalable.


    Note –

    To determine the command line that you need to type, check the customized man page or run the startapp script without any arguments to display a usage statement.

    To view the man pages, you need to specify the path to the man page. For example, to view the startapp(1M) man page, type:


    # man -M /opt/NETapp/man startapp
    

    To display a usage statement, type:


    # /opt/NETapp/util/startapp
     The resource name of LogicalHostname or SharedAddress must be specified.
     For failover services:
     Usage: startapp -h logicalhostname
              -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]