rcm_scriptname scriptinfo

rcm_scriptname register

rcm_scriptname resourceinfo resourcename

rcm_scriptname queryremove resourcename

rcm_scriptname preremove resourcename

rcm_scriptname postremove resourcename

rcm_scriptname undoremove resourcename

Reconfiguration and Coordination Manager (RCM) is a framework designed to coordinate device consumers during Solaris Dynamic Reconfiguration (DR). The interfaces specified in this man page allow device consumers, such as application vendors or site administrators, to act before and after DR operations take place by providing RCM scripts. You can write your own RCM scripts to shut down your applications, or to cleanly release the devices from your applications during dynamic remove operations.

An RCM script is an executable perl script, a shell script or a binary. Perl is the recommended language. Each script is run in its own address space using the user-id of the script file owner.

An RCM script is invoked on demand in response to DR as follows:

<scriptname> <command> [args ...]

Every script must implement the following RCM commands:

scriptinfo

register

resourceinfo

A script might include some or all the of the following commands:

queryremove

preremove

postremove

undoremove

When a script's register command is run, the script should supply, in return data, all resource names the script or its application handles that could potentially be removed by DR. A resource name refers to a name in /dev path name.

Below is a high-level overview of the sequence of script invocations that occurs when dynamic removal of a script's registered resource is attempted. See the COMMANDS section for a detailed description of the commands.

<scriptname> queryremove <resourcename>

<scriptname> preremove <resourcename>

<scriptname> postremove <resourcename>

<scriptname> undoremove <resourcename>

For any commands the script does not implement, it must exit with exit status of 2. RCM silently returns success for the script's unimplemented commands.

A script performs the following basic steps:

The initial environment of RCM scripts is set as follows:

All environment variable names beginning with RCM_ENV_ are reserved for use by the RCM.

The character encoding used by the RCM and RCM scripts to exchange RCM commands, environment parameters, and name-value pairs is ASCII unless the controlling environment variables are specified otherwise.

The scriptinfo command is invoked to gather information about the script.

Return data:

The register command is invoked to allow a script to specify the resources that it or its application handles that could potentially be removed by DR. The script has to supply all its resource names to RCM using the name-value pair rcm_resource_name.

Return Data:

rcm_resource_name=resourcename
rcm_resource_name=resourcename
 .
 .
 .

The resourceinfo command is invoked to get the usage information about resourcename.

Return Data:

rcm_resource_usage_info=resource_usage

Prior to removing the resource from the system, the queryremove command is invoked to query the script to determine whether the script can release the given resource successfully from the service or application it represents. The script does not actually release the resource. The script might indicate that it is not able to release the resource if the resource is critical for its service or application.

Additional environment parameter:

RCM_ENV_FORCE

Return Data:

The preremove command is invoked prior to an attempt to remove the given resourcename. In response to this command the script can either release the resource (including closing the device if the device is currently opened) from the service or application it represents or indicate that it can not release the resource if the resource is critical for its service or application.

Additional environment parameter:

RCM_ENV_FORCE

Return Data:

The postremove command is invoked after the given resourcename has been removed.

Return Data:

undoremove resourcename

The undoremove command is invoked to undo what was done in the previous preremove command for the given resourcename. The script can bring the state of the resource to the same state it was in when the script received the preremove command for that resource.

Return Data:

A script must log all error and debug messages by writing to stdout the name-value pairs listed below. The logged messages go to syslogd(1M) with the syslog facility of LOG_DAEMON. See syslog.conf(4).

rcm_log_err=message

rcm_log_warn=message

rcm_log_info=message

rcm_log_debug=message

A script can use the environment variable RCM_ENV_DEBUG_LEVEL to control the amount of information to log. RCM_ENV_DEBUG_LEVEL is a numeric value ranging from 0 to 9, with 0 meaning log the least amount of information and 9 meaning log the most.

You must use the following format to name a script:

vendor,service

where vendor is the stock symbol (or any distinctive name) of the vendor providing the script and service is the name of service the script represents.

You must be a superuser (root) to install or remove an RCM script.

Select one of the following directories where you want to place the script:

/etc/rcm/scripts

/usr/platform/`uname -i`/lib/rcm/scripts

/usr/platform/`uname -m`/lib/rcm/scripts

/usr/lib/rcm/scripts

To install a script, copy the script to the appropriate directory from the list above, change the userid and the groupid of the script to the desired values, and send SIGHUP to rcm_daemon. For example:

# cp SUNW,sample.pl /usr/lib/rcm/scripts
# chown user[:group] /usr/lib/rcm/scripts/SUNW,sample.pl
# pkill -HUP -x -u root rcm_daemon

Remove the script from the appropriate directory from the list above and send SIGHUP to rcm_daemon. For example:

# rm /usr/lib/rcm/scripts/SUNW,sample.pl
# pkill -HUP -x -u root rcm_daemon

Example 1 Site Customization RCM Script

#! /usr/bin/perl -w

#
# A sample site customization RCM script for a tape backup application.
#
# This script registers all tape drives in the system with RCM.
# When the system attempts to remove a tape drive by DR the script
# does the following:
# - if the tape drive is not being used for backup, it allows the
# DR to continue.
# - if the tape drive is being used for backup, and when DR is not
# forced (RCM_ENV_FORCE=FALSE) it indicates that it cannot release 
# the tape drive with appropriate error message. When forced
# (RCM_ENV_FORCE=TRUE) it kills the tape backup application in
# order to allow the DR to continue.
#
# This script does not implement the postremove and undoremove commands
# since there is nothing to cleanup after DR remove operation is 
# completed or failed. If any cleanup is needed after the DR removal 
# completed, postremove command needs to implemented. If any cleanup is 
# needed in the event of DR removal failure, undoremove command needs 
# to be implemented.
#

use strict;

my ($cmd, %dispatch);

$cmd = shift(@ARGV);

# dispatch table for RCM commands
%dispatch = (
 "scriptinfo" => do_scriptinfo,
 "register" => do_register,
 "resourceinfo" => do_resourceinfo,
 "queryremove" => do_preremove,
 "preremove" => do_preremove 
);

if (defined($dispatch{$cmd})) {
 &{$dispatch{$cmd}};
} else {
 exit (2);
}

sub do_scriptinfo
{
 print "rcm_script_version=1\en";
 print "rcm_script_func_info=Tape backup appl script for DR\en";
 exit (0);
}

sub do_register
{
 my ($dir, $f, $errmsg);

 $dir = opendir(RMT, "/dev/rmt");
 if (!$dir) {
 $errmsg = "Unable to open /dev/rmt directory: $!";
 print "rcm_failure_reason=$errmsg\en";
 exit (1);
 }

 while ($f = readdir(RMT)) {
 # ignore hidden files and multiple names for the same device
 if (($f !~ /^\./) && ($f =~ /^[0-9]+$/)) {
 print "rcm_resource_name=/dev/rmt/$f\en";
 }

 }

 closedir(RMT);
 exit (0);
}

sub do_resourceinfo
{
 my ($rsrc, $unit);

 $rsrc = shift(@ARGV);
 if ($rsrc =~ /^\/dev\/rmt\/([0-9]+)$/) {
 $unit = $1;
 print "rcm_resource_usage_info=Backup Tape Unit Number $unit\en";
 exit (0);
 } else {
 print "rcm_failure_reason=Unknown tape device!\en";
 exit (1);
 }
}

sub do_preremove
{
 my ($rsrc);

 $rsrc = shift(@ARGV);

 # check if backup application is using this resource
 # if (the backup application is not running on $rsrc) {
 # allow the DR to continue
 # exit (0);
 #}
 #
 # If RCM_ENV_FORCE is FALSE deny the operation.
 # If RCM_ENV_FORCE is TRUE kill the backup application in order
 # to allow the DR operation to proceed
 #
 if ($ENV{RCM_ENV_FORCE} eq 'TRUE') {
 if ($cmd eq 'preremove') {
 # kill the tape backup application
 }
 exit (0);
 } else {
 #
 # indicate that the tape drive can not be released
 # since the device is being used for backup by the
 # tape backup application
 #
 print "rcm_failure_reason=tape backup in progress pid=...\en";
 exit (3);

 }
}

A script must exit with following exit status values:

0

1

2

3

If a script cannot successfully process an RCM command, it must supply to the RCM a message indicating the reason for failure by writing a name-value pair, in the form shown below, to stdout and exiting with the appropriate exit status.

rcm_failure_reason=failure_reason

where failure_reason is a localized human readable message describing the reason for failure of the RCM command.

See attributes(5) for descriptions of the following attributes:

gettext(1), cfgadm(1M), cfgadm_scsi(1M), cfgadm_pci(1M), syslog(3C), signal.h(3HEAD), syslog.conf(4), attributes(5), environ(5)

RCM scripts are expected to properly handle all RCM commands that the script implements and to log all errors. Only root has permission to add or remove an RCM script. An ill-behaved RCM script can cause unexpected DR failures.

RCM commands are invoked only for the resources whose subsystems participate within the RCM framework. Currently, not all susbsystems participate within the RCM framework.