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 the SunPlex Agent Builder or the standard Sun Cluster administration commands.
This chapter contains the following topics:
Using SunPlex Agent Builder to Create a Service That Uses the GDS
Using the Standard Sun Cluster Administration Commands to Create a Service That Uses the GDS
The GDS is a mechanism for making simple network aware and non-network 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 an agent, which you typically must do to make 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)).
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 |
The GDS has the following advantages over using either the SunPlex Agent Builder generated source code model (see the scdscreate(1HA) man page) or the standard Sun Cluster administration commands:
The GDS is easy to use.
The GDS and its methods are precompiled and therefore cannot be modified.
The SunPlex Agent Builder can be used to generate scripts for your application and these scripts are put in a Solaris package that can be reused across multiple clusters.
While using the GDS has many advantages, there are instances when it is not the mechanism to use. The GDS is not the mechanism to use in these instances:
More control is required than is available using the precompiled resource type, such as when you need to add extension properties or change default values
The source code needs to be modified to add special functions
There are two ways to create a service that uses the GDS:
Using the SunPlex Agent Builder
Using the standard Sun Cluster administration commands
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 scripts that configure resources for the given application.
This method uses the precompiled data service code in SUNWscgds but requires that the system administrator use standard Sun Cluster administration commands to create and configure the resource. See the scrgadm(1M) and scswitch(1M) man pages.
As shown in the procedures 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, a significant amount of typing is required to issue the appropriate scrgadm and scswitch commands.
Using GDS with SunPlex Agent Builder simplifies the process because it generates the scripts that issue the scrgadm and scswitch commands for you.
The GDS enables you to log relevant information that is passed from the GDS to the scripts that the GDS launches. This relevant information includes the status of the start, probe, 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.
The following two GDS log files are placed in the directory /var/cluster/logs/DS/resource_group_name/resource_name:
start_stop_log.txt, which contains messages that are logged by resource start and stop methods
probe_log.txt, which contains messages that are logged by the resource monitor
The following example shows the types of information that start_stop_log.txt contains:
10/20/2004 12:38:05 phys-node-1 START-INFO> Start succeeded. [/home/brianx/sc/start_cmd] 10/20/2004 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:
10/20/2004 12:38:15 phys-node-1 PROBE-INFO> The GDS monitor (gds_probe) has been started 10/20/2004 12:39:15 phys-node-1 PROBE-INFO> The probe result is 0 10/20/2004 12:40:15 phys-node-1 PROBE-INFO> The probe result is 0 10/20/2004 12:41:15 phys-node-1 PROBE-INFO> The probe result is 0
If your application is non-network aware, you must provide both the Start_command extension property and the Port_list property. If your application is network aware, you must provide only the Port_list property.
The start command, which you specify in the Start_command extension property, launches the application. It must be a UNIX command with arguments that can be passed directly to a shell to start the application.
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 is created by SunPlex Agent Builder or with the scrgadm command if you are using the standard Sun Cluster administration commands.
The following list contains optional GDS properties:
Network_resources_used
Stop_command (extension property)
Probe_command (extension property)
Start_timeout
Stop_timeout
Probe_timeout (extension property)
Child_mon_level (extension property used only with the standard administration commands)
Failover_enabled (extension property)
Stop_signal (extension property)
Log_level (extension 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 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 or one or more SharedAddress. See the r_properties(5) man page 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 extension property is provided, the GDS stop method launches the stop command with 80 percent of the stop timeout. Regardless of the outcome of launching 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 using the signal specified in Stop_signal.
The probe command periodically checks the health of the given application. It 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 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 causes the application to immediately fail over unless Failover_enabled is set to FALSE. The probe status is used within the GDS probing algorithm (see the scds_fm_action(3HA) man page) 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 that are derived from the Network_resources_used property or the output of scds_get_netaddr_list (see the scds_get_netaddr_list(3HA) man page). If the connect succeeds, it disconnects immediately. If both connect and disconnect succeed, the application is deemed to be running healthily.
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 Extension Property for additional information. The default for Start_timeout is 300 seconds.
This property specifies the stop timeout for the stop command. See Stop_command Property for additional information. The default for Stop_timeout is 300 seconds.
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.
If you use the standard Sun Cluster administration commands, you can use this option. If you use SunPlex Agent Builder, you cannot use this option.
This property provides control over the processes that are monitored through the Process Monitor Facility (PMF). It 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.
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 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 property can be used to prevent the application resource from initiating a failover of the resource group. The default value for this property is true.
The GDS uses the value of this integer extension property to determine the signal used for stopping the application through PMF. See the signal(3HEAD) man page for a list of the integer values that you can specify. The default value is 15 (SIGTERM).
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 information messages are logged. And when you specify ERR, only error messages are logged. By default, the GDS does not log diagnostic messages (NONE).
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.
Become superuser or assume an equivalent role.
Start the SunPlex Agent Builder.
# /usr/cluster/bin/scdsbuilder |
The SunPlex Agent Builder Create screen appears.
Type the Vendor Name.
Type the Application Name.
The combination of Vendor and Application Name cannot contain more than nine characters. It is used as the name of the package for the scripts.
Go to the working directory.
You can use the Browse pull-down menu to select the directory rather than typing the path.
Select whether the data service is scalable or failover.
You do not need to select Network Aware since that is the default when you create the GDS.
Select GDS.
(Optional) Change the RT Version from the default value that is shown.
You cannot use the following characters in the RT Version field: blank, tab, slash (/), backslash (\), asterisk (*), question mark (?), comma (,), semicolon (;), left square bracket ([), or right square bracket (]).
Click Create.
Agent Builder creates the scripts. Results of the creation of the service are displayed in the Output Log window.
Create is grayed out. You can now configure the scripts.
Click Next.
The Configuration screen appears.
After creating the scripts, you need to configure the new service.
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 Property Variables.
(Optional) Type the stop command or click Browse to locate the stop command.
You can specify property variables. Property variables are described in Property Variables.
(Optional) Type the probe command or click Browse to locate the probe command.
You can specify property variables. Property variables are described in Property Variables.
(Optional) Specify the timeout values for the start, stop, and probe commands.
Click Configure.
Agent Builder starts to configure the scripts.
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_nameapplication/pkg |
For example, /export/wdir/NETapp/pkg.
As superuser, install the completed package on all nodes of the cluster.
# 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 |
The man pages and script names correspond to the Application Name that you entered previously 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(1M) man page, type:
# man -M /opt/NETapp/man startapp |
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. Check the customized man page or run the startapp script without any arguments to display a usage statement.
# /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] |
The SunPlex Agent Builder generates three scripts and a configuration file based on input that you provide when the package is created. The configuration file specifies the names of the resource group and resource type.
The scripts are:
Start script: Used to configure the resources and start the application that is 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 that are created by the start script.
These scripts have the same interface and behavior as the utility scripts that are generated by the SunPlex Agent Builder for non-GDS-based agents. The scripts are put in a Solaris 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 default values for the scrgadm parameters.
This section describes how to input parameters to the GDS. You use the existing Sun Cluster administration commands, such as scrgadm and scswitch, to use and administer the GDS.
You do not need to enter the lower-level administration commands that are shown in this section if the scripts provide adequate functionality. However, you can enter the lower-level administration commands if you need to have finer control over the GDS-based resource. These commands are executed by the scripts.
Become superuser or assume an equivalent role.
Register the resource type SUNW.gds
# scrgadm -a -t SUNW.gds |
Create the resource group that contains the LogicalHostname resource and the failover service itself.
# scrgadm -a -g haapp_rg |
Create the resource for the LogicalHostname resource.
# scrgadm -a -L -g haapp_rs -l hhead |
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 |
Bring the resource group haapp_rg online.
# scswitch -Z -g haapp_rg |
Become superuser or assume an equivalent role.
Register the resource type SUNW.gds.
# scrgadm -a -t SUNW.gds |
Create the resource group for the SharedAddress resource.
# scrgadm -a -g sa_rg |
Create the SharedAddress resource on sa_rg.
# scrgadm -a -S -g sa_rg -l hhead |
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 |
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 |
Bring the resource group that contains the network resources online.
# scswitch -Z -g sa_rg |
Bring the resource group app_rg online.
# scswitch -Z -g app_rg |
The SunPlex Agent Builder also incorporates a command-line interface that provides the same functionality that the graphical user interface provides. This interface consists of the commands scdscreate and scdsconfig. See the scdscreate(1HA) and scdsconfig(1HA) man pages.
This section describes how to perform the same set of steps shown in Using SunPlex Agent Builder to Create a Service That Uses the GDS by using the command-line interface.
Become superuser or assume an equivalent role.
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 |
The -d parameter is optional. If you do not specify this parameter, the current directory becomes the working directory.
Configure the service.
# scdsconfig -s "/export/app/bin/start" -t "/export/app/bin/stop" \ -m "/export/app/bin/probe" -d /export/wdir |
You can specify property variables. Property variables are described in Property Variables.
Only the start command is required. All other parameters are optional.
Install the completed package on all nodes of the cluster.
# 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 |
The man pages and script names correspond to the Application Name that you entered previously 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(1M) man page, type:
# man -M /opt/NETapp/man startapp |
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. Check the customized man page or run the startapp script without any arguments to display a usage statement.
# /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] |