JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Oracle Solaris Cluster Data Services Developer's Guide     Oracle Solaris Cluster 3.3 3/13
search filter icon
search icon

Document Information

Preface

1.  Overview of Resource Management

2.  Developing a Data Service

Analyzing the Application for Suitability

Determining the Interface to Use

Setting Up the Development Environment for Writing a Data Service

How to Set Up the Development Environment

Transferring a Data Service to a Cluster

Setting Standard Properties

Cluster Properties

Resource Type Properties

Resource Properties

Resource Group Properties

Resource Property Attributes

Node List Properties

Setting Resource and Resource Type Properties

Declaring Resource Type Properties

Declaring Resource Type Properties for a Zone Cluster

Declaring Resource Properties

Declaring Extension Properties

Implementing Callback Methods

Accessing Resource and Resource Group Property Information

Idempotence of Methods

How Methods Are Invoked in Zones

Generic Data Service

Controlling an Application

Starting and Stopping a Resource

Using Start and Stop Methods

Deciding Which Start and Stop Methods to Use

Using the Optional Init, Fini, and Boot Methods

Using the Init Method

Using the Fini Method

Guidelines for Implementing a Fini Method

Using the Boot Method

Monitoring a Resource

Implementing Monitors and Methods That Execute Exclusively in the Global Zone

Adding Message Logging to a Resource

Providing Process Management

Providing Administrative Support for a Resource

Implementing a Failover Resource

Implementing a Scalable Resource

Validation Checks for Scalable Services

Writing and Testing Data Services

Using TCP Keep-Alives to Protect the Server

Testing HA Data Services

Coordinating Dependencies Between Resources

Legal RGM Names

RGM Legal Names

Rules for Names Except Resource Type Names

Format of Resource Type Names

RGM Values

3.  Resource Management API Reference

4.  Modifying a Resource Type

5.  Sample Data Service

6.  Data Service Development Library

7.  Designing Resource Types

8.  Sample DSDL Resource Type Implementation

9.  Oracle Solaris Cluster Agent Builder

10.  Generic Data Service

11.  DSDL API Functions

12.  Cluster Reconfiguration Notification Protocol

13.  Security for Data Services

A.  Sample Data Service Code Listings

B.  DSDL Sample Resource Type Code Listings

C.  Requirements for Non-Cluster Aware Applications

D.  Document Type Definitions for the CRNP

E.  CrnpClient.java Application

Index

Monitoring a Resource

Typically, you implement monitors to run periodic fault probes on resources to detect whether the probed resources are working correctly. If a fault probe fails, the monitor can attempt to restart locally or request failover of the affected resource group. The monitor requests the failover by calling the scha_control() or scha_control_zone() RMAPI function or the scds_fm_action() DSDL function.

You can also monitor the performance of a resource and tune or report performance. Writing a resource type-specific fault monitor is optional. Even if you choose not to write such a fault monitor, the resource type benefits from the basic monitoring of the cluster that Oracle Solaris Cluster software itself does. Oracle Solaris Cluster software detects failures of the host hardware, gross failures of the host's operating system, and failures of a host to be able to communicate on its public networks.

Although the RGM does not call a resource monitor directly, the RGM does provide for automatically starting monitors for resources. When bringing a resource offline, the RGM calls the Monitor_stop method to stop the resource's monitor on the local nodes before stopping the resource itself. When bringing a resource online, the RGM calls the Monitor_start method after the resource itself has been started.

The scha_control() or scha_control_zone() RMAPI function and the scds_fm_action() DSDL function (which calls scha_control()) enable resource monitors to request the failover of a resource group to a different node. As one of its sanity checks, scha_control() and scha_control_zone() call Monitor_check (if defined) to determine whether the requested node is reliable enough to master the resource group that contains the resource. If Monitor_check reports back that the node is not reliable, or the method times out, the RGM looks for a different node to honor the failover request. If Monitor_check fails on all nodes, the failover is canceled.

The resource monitor can set the Status and Status_msg properties to reflect the monitor's view of the resource state. Use the scha_resource_setstatus() or scha_resource_setstatus_zone() RMAPI function, the scha_resource_setstatus command, or the scds_fm_action() DSDL function to set these properties.


Note - Although the Status and Status_msg properties are of particular use to a resource monitor, any program can set these properties.


See Defining a Fault Monitor for an example of a fault monitor that is implemented with the RMAPI. See ORCL.xfnts Fault Monitor for an example of a fault monitor that is implemented with the DSDL. See the Oracle Solaris Cluster Data Services Planning and Administration Guide for information about fault monitors that are built into data services that are supplied by Oracle.

Implementing Monitors and Methods That Execute Exclusively in the Global Zone

Most resource types execute their methods in whatever node appears in the resource group's node list. A few resource types must execute all of their methods in the global zone, even when the resource group is configured in a non-global zone, that is, either a zone-cluster node or a global-cluster nonvoting node. This is necessary for resource types that manage system resources, such as network addresses or disks, which can only be managed from the global zone. These resource types are identified by setting the Global_zone property to TRUE in the resource type registration (RTR) file.


Caution

Caution - Do not register a resource type for which the Global_zone property is set to TRUE unless the resource type comes from a known and trusted source. Resource types for which this property is set to TRUE circumvent zone isolation and present a risk.


A resource type that declares Global_zone=TRUE might also declare the Global_zone_override resource property. In this case, the value of the Global_zone_override property supersedes the value of the Global_zone property for that resource. The Global_zone_override property is described in more detail in Resource Properties and the r_properties(5) man page.

If the Global_zone resource type property is not set to TRUE, monitors and methods execute in whatever nodes are listed in the resource group's node list.

The scha_control() and scha_resource_setstatus() functions and the scha_control and scha_resource_setstatus commands operate implicitly on the node from which the function or command is run. If the Global_zone resource type property equals TRUE, these functions and commands need to be invoked differently when the resource is configured in a non-global zone.

When the resource is configured in a non-global zone, the value of the zonename operand is passed to the resource type method by the -Z option. If your method or monitor invokes one of these functions or commands without the correct handling, it incorrectly operates on the global zone. Your method or monitor should operate on the non-global zone in which the resource that is included in the resource group's node list is configured.

To ensure that your method or monitor code handles these conditions correctly, check that it does the following:

If a resource for which the Global_zone resource type property equals TRUE invokes scha_cluster_get() with the ZONE_LOCAL query optag value, it returns the name of the global zone. In this case, the calling code must concatenate the string :zonename to the local node name to obtain the zone in which the resource is actually configured. The zonename is the same zone name that is passed down to the method in the -Z zonename command-line option. If there is no -Z option in the command line, the resource group is configured in the global zone and you do not need to concatenate a zone name to the node name.

Similarly, if the calling code queries, for example, the state of a resource in the non-global zone, it must invoke scha_resource_get() with the RESOURCE_STATE_NODE optag value rather than the RESOURCE_STATE optag value. In this case, the RESOURCE_STATE optag value queries in the global zone rather than in the non-global zone in which the resource is actually configured.

The DSDL functions inherently handle the -Z zonename option. Therefore, the scds_initialize() function obtains the relevant resource and resource group properties for the non-global zone in which a resource is actually configured. Other DSDL queries operate implicitly on that node.

You can use the DSDL function scds_get_zone_name() to query the name of the zone that is passed to the method in the -Z zonename command-line option. If no -Z zonename is passed, the scds_get_zone_name() function returns NULL.

Multiple Boot methods might run simultaneously in the global zone if both of the following conditions occur: