Utility Functions

Oracle^® Solaris Cluster Data Services Developer's Guide

Document Information

Using This Documentation

Product Documentation Library

Access to Oracle Support

Documentation Accessibility

Feedback

Chapter 1 Overview of Resource Management

Oracle Solaris Cluster Application Environment

Resource Group Manager Model

Description of a Resource Type

Description of a Resource

Description of a Resource Group

Resource Group Manager

Callback Methods

Programming Interfaces

Resource Management API

Data Service Development Library

Oracle Solaris Cluster Agent Builder

Resource Group Manager Administrative Interface

Oracle Solaris Cluster Manager

clsetup Utility

Administrative Commands

Chapter 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 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

Chapter 3 Resource Management API Reference

RMAPI Access Methods

RMAPI Shell Commands

RMAPI Resource Commands

Resource Type Command

Resource Group Commands

Cluster Command

C Functions

Resource Functions

Resource Type Functions

Resource Group Functions

Cluster Functions

Utility Function

RMAPI Callback Methods

Arguments That You Can Provide to Callback Methods

Callback Method Exit Codes

Control and Initialization Callback Methods

Administrative Support Methods

Net-Relative Callback Methods

Monitor Control Callback Methods

Chapter 4 Modifying a Resource Type

Overview of Modifying a Resource Type

Setting Up the Contents of the Resource Type Registration File

Resource Type Name

Specifying the #$upgrade and #$upgrade_from Directives

Changing the RT_version in an RTR File

What Happens When a Cluster Administrator Upgrades

Determining Installation Requirements and Packaging

Before You Change the RTR File

Changing Monitor Code

Changing Method Code

Determining the Packaging Scheme to Use

Documentation to Provide for a Modified Resource Type

Information About What to Do Before Installing an Upgrade

Information About When to Upgrade Resources

Information About Changes to Resource Properties

Chapter 5 Sample Data Service

Overview of the Sample Data Service

Defining the Resource Type Registration File

Overview of the RTR File

Resource Type Properties in the Sample RTR File

Resource Properties in the Sample RTR File

System-Defined Properties in the RTR File

Extension Properties in the RTR File

Providing Common Functionality to All Methods

Identifying the Command Interpreter and Exporting the Path

Declaring the PMF_TAG and SYSLOG_TAG Variables

Parsing the Function Arguments

Generating Error Messages

Obtaining Property Information

Controlling the Data Service

How the Start Method Works

What the Start Method Does

Verifying the Configuration

Starting the Application

Start Exit Status

How the Stop Method Works

What the Stop Method Does

Stopping the Application

Stop Exit Status

Defining a Fault Monitor

How the Probe Program Works

What the Probe Program Does

Obtaining Property Values

Checking the Reliability of the Service

Comparing Restart With Failover

Restarting the Data Service

Probe Exit Status

How the Monitor_start Method Works

What the Monitor_start Method Does

Starting the Probe

How the Monitor_stop Method Works

What the Monitor_stop Method Does

Stopping the Monitor

Monitor_stop Exit Status

How the Monitor_check Method Works

Handling Property Updates

How the Validate Method Works

What the Validate Method Does

Validate Method Parsing Function

Validating Confdir

Validate Exit Status

How the Update Method Works

What the Update Method Does

Stopping the Monitor With Update

Restarting the Monitor

Update Exit Status

Chapter 6 Data Service Development Library

DSDL Overview

Managing Configuration Properties

Starting and Stopping a Data Service

Implementing a Fault Monitor

Accessing Network Address Information

Debugging the Resource Type Implementation

Enabling Highly Available Local File Systems

Chapter 7 Designing Resource Types

Resource Type Registration File

Description of Init, Fini, and Boot Methods

Designing the Fault Monitor Daemon

Supporting Resource Types That Perform Resource Migration From Their Stop Method

SCHA_TARGET_NODES Query

Pre_evict Resource Property

Example of a Giveover of a Resource Group With Live Migration

Error Handling

Chapter 8 Sample DSDL Resource Type Implementation

X Font Server

X Font Server Configuration File

TCP Port Number

ORCL.xfnts RTR File

Naming Conventions for Functions and Callback Methods

scds_initialize Function

xfnts_start Method

Validating the Service Before Starting the X Font Server

Starting the Service With svc_start

Returning From svc_start

xfnts_stop Method

xfnts_monitor_start Method

xfnts_monitor_stop Method

xfnts_monitor_check Method

ORCL.xfnts Fault Monitor

xfonts_probe Main Loop

svc_probe Function

Determining the Fault Monitor Action

xfnts_validate Method

xfnts_update Method

Chapter 9 Oracle Solaris Cluster Agent Builder

Agent Builder Overview

Before You Use Agent Builder

Using Agent Builder

Analyzing the Application

Installing and Configuring Agent Builder

Agent Builder Screens

Starting Agent Builder

Navigating Agent Builder

Browse Command

Agent Builder Menus

Agent Builder File Menu

Agent Builder Edit Menu

Using the Create Screen

Using the Configure Screen

Using the Agent Builder Korn Shell-Based $hostnames Variable

Using Property Variables

List of Property Variables

Resource Property Variables

Resource Type Property Variables

Resource Group Property Variables

Syntax of Property Variables

How Agent Builder Substitutes Property Variables

Reusing Code That You Create With Agent Builder

How to Clone an Existing Resource Type

Editing the Generated Source Code

How to Use the Command-Line Version of Agent Builder

Directory Structure That Agent Builder Creates

Agent Builder Output

Source and Binary Files

Utility Scripts and Man Pages That Agent Builder Creates

Support Files That Agent Builder Creates

Package Directory That Agent Builder Creates

rtconfig File

Chapter 10 DSDL API Functions

General-Purpose Functions

Initialization Functions

Retrieval Functions

Failover and Restart Functions

Execution Functions

Property Functions

Network Resource Access Functions

Host Name Functions

Port List Functions

Network Address Functions

Fault Monitoring Using TCP Connections Functions

PMF Functions

Fault Monitor Functions

Utility Functions

Chapter 11 Cluster Reconfiguration Notification Protocol

How a Client Registers With the Server

Assumptions About How Administrators Set Up the Server

How the Server Identifies a Client

How SC_CALLBACK_REG Messages Are Passed Between a Client and the Server

Contents of an SC_CALLBACK_REG Message

How the Server Replies to a Client

Contents of an SC_REPLY Message

How a Client Is to Handle Error Conditions

How the Server Delivers Events to a Client

How the Delivery of Events Is Guaranteed

Contents of an SC_EVENT Message

How the CRNP Authenticates Clients and the Server

Example of Creating a Java Application That Uses the CRNP

How to Set Up Your Environment

How to Start Developing Your Application

How to Parse the Command-Line Arguments

How to Define the Event Reception Thread

How to Register and Unregister Callbacks

How to Generate the XML

How to Create the Registration and Unregistration Messages

How to Set Up the XML Parser

How to Parse the Registration Reply

How to Parse the Callback Events

How to Run the Application

Chapter 12 Security for Data Services

Storing Application Passwords in Private Strings

Invoking Application Programs with Least Privilege

Using the resource_security Property

Using the application_user Property

Using the scha_check_app_user Command

Executing the Application Under a Specified Oracle Solaris Project

Appendix A Sample Data Service Code Listings

Resource Type Registration File Listing

Start Method Code Listing

Stop Method Code Listing

gettime Utility Code Listing

PROBE Program Code Listing

Monitor_start Method Code Listing

Monitor_stop Method Code Listing

Monitor_check Method Code Listing

Validate Method Code Listing

Update Method Code Listing

Appendix B DSDL Sample Resource Type Code Listings

xfnts.c File Listing

xfnts_monitor_check Method Code Listing

xfnts_monitor_start Method Code Listing

xfnts_monitor_stop Method Code Listing

xfnts_probe Method Code Listing

xfnts_start Method Code Listing

xfnts_stop Method Code Listing

xfnts_update Method Code Listing

xfnts_validate Method Code Listing

Appendix C Requirements for Non-Cluster-Aware Applications

Multihosted Data

Using Symbolic Links for Multihosted Data Placement

Host Names

Multihomed Hosts

Binding to INADDR_ANY as Opposed to Binding to Specific IP Addresses

Client Retry

Appendix D Document Type Definitions for the CRNP

SC_CALLBACK_REG XML DTD

NVPAIR XML DTD

SC_REPLY XML DTD

SC_EVENT XML DTD

Appendix E CrnpClient.java Application

Contents of CrnpClient.java

Index

Index Numbers and Symbols

Language:

The following functions enable you to write messages and debugging messages to the system log:

scds_syslog(3HA) – Writes messages to the system log.
scds_syslog_debug(3HA) – Writes debugging messages to the system log.