Skip Navigation Links
Exit Print View
| Oracle Solaris Cluster Reference Manual Oracle Solaris Cluster 4.1

Search Scope:

- This Document
- Entire Library

### SUNW.gds

- resource type for making simple network-aware and non-network-aware applications highly available or scalable

## Description

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

The GDS contains a fully functional Oracle Solaris Cluster resource type, complete with callback methods (`rt_callbacks`(1HA)) and a Resource Type Registration (RTR) file (`rt_reg`(4)).

### Standard Properties

`Failover_mode` (`enum`)

  Modifies the recovery actions that the RGM takes when a resource fails to start or stop successfully, or when a resource monitor finds a resource to be unhealthy and consequently requests a restart or failover.

  For more information on the `Failover_mode` property, see the `r_properties`(5) man page.

  Category

    Optional

  Default

    SOFT

  Tunable

    Any time

`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 network-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

    When disabled

`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 Oracle Solaris Cluster administration commands.

  Note - If the `Network_aware` property is set to `False`, the `Port_list` property is not required.

  Appended to each port number is a slash (`/`) followed by the protocol that is being used by that port, for example, `Port_list=80/tcp` or `Port_list=80/tcp6,40/udp6`.

  You can specify the following protocol values:

  - `tcp`, for TCP IPv4

  - `tcp6`, for TCP IPv6

  - `udp`, for UDP IPv4

  - `udp6`, for UDP IPv6

  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 `clreslogicalhostname`(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_properties`(5) man page.

  Category

    Optional

  Default

    The empty list

  Tunable

    Any time

`Retry_count` (`integer`)

  The number of times a monitor attempts to restart a resource if it fails.

  For more information on the `Retry_count` property, see the `r_properties`(5) man page.

  Category

    Conditional

  Default

    2

  Tunable

    Any time

`Retry_interval` (`integer`)

  The number of seconds in which to count attempts to restart a failed resource.

  For more information on the `Retry_interval` property, see the `r_properties`(5) man page.

  Category

    Conditional

  Default

    370 seconds

  Tunable

    Any time

`Scalable` (`boolean`)

  Indicates whether the resource is scalable, that is, whether the resource uses the networking load balancing features of Oracle Solaris Cluster software.

  If the `Scalable` property is set to `TRUE`, then additional properties such as `Load_balancing_policy` and `Load_balancing_weights` are used to configure the load balancing behavior.

  For more information on the `Scalable`, `Load_balancing_policy`, and `Load_balancing_weights` properties, see the `r_properties`(5) man page.

  Category

    Optional

  Default

    FALSE

  Tunable

    At creation

`Start_timeout` (`integer`)

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

  Category

    Optional

  Minimum

    60 seconds

  Default

    300 seconds

  Tunable

    Any time

`Stop_timeout` (`integer`)

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

  Category

    Optional

  Minimum

    60 seconds

  Default

    300 seconds

  Tunable

    Any time

`Validate_timeout` (`integer`)

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

  Category

    Optional

  Minimum

    60 seconds

  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.

  Category

    Optional

  Default

    `True`

  Tunable

    When disabled

  Note - The `Failover_mode=RESTART_ONLY` setting matches the behavior of the `Failover_enabled=False` setting. The `Failover_mode=LOG_ONLY` setting goes a step further and prevents resources from restarting. Use the `Failover_mode` property instead of the `Failover_enabled` extension property to better control failover behavior. For more information, see the descriptions of the `LOG_ONLY` and `RESTART_ONLY` values for `Failover_mode` in `r_properties`(5).

`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

`Monitor_retry_count`

  The number of times that the process monitor facility (PMF) restarts the fault monitor during the time window that the `Monitor_retry_interval` property specifies. This property refers to restarts of the fault monitor itself rather than to the resource. The system-defined properties `Retry_interval` and `Retry_count` control restarting of the resource.

  Category

    Optional

  Data type

    Integer

  Default

    `4`

  Range

    `0` - `2147483647`

    `-1` indicates an infinite number of retry attempts.

  Tunable

    At any time

`Monitor_retry_interval`

  The time (in minutes) over which failures of the fault monitor are counted. If the number of times that the fault monitor fails exceeds the value that is specified in the extension property `Monitor_retry_count` within this period, the PMF does not restart the fault monitor.

  Category

    Optional

  Data type

    Integer

  Default

    `2`

  Range

    `0` – `2147483647`

    `-1` indicates an infinite retry interval.

  Tunable

    At 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 non network-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. If the `probe` command is omitted, the GDS provides its own simple probe that connects to the application 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 non-network-aware applications. However, a non-network-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

  Minimum

    2 seconds

  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 service 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 different node.

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

  Category

    Required

  Minimum

    1

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

  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

  Minimum

    1

  Maximum

    37

  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. If the command exits nonzero, the giveover is blocked and the resource group remains mastered on its current node.

  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 Oracle Solaris 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 | `ha-cluster/ha-service/gds`

## See Also

`clreslogicalhostname`(1CL), `clresource`(1CL), `clresourcegroup`(1CL), `clresourcetype`(1CL), `clressharedaddress`(1CL), `rt_callbacks`(1HA), `scdsbuilder`(1HA), `scha_control`(1HA), `scha_resource_get`(1HA), `hatimerun`(1M), `pmfadm`(1M), `signal`(3HEAD), `rt_reg`(4), `attributes`(5), `r_properties`(5), `scalable_service`(5)

Copyright © 2000, 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |