File Formats rcmscript(4)
NAME
rcmscript - script interface specification for the Reconfi-
guration and Coordination Manager
SYNOPSIS
rcmscriptname scriptinfo
rcmscriptname register
rcmscriptname resourceinfo resourcename
rcmscriptname queryremove resourcename
rcmscriptname preremove resourcename
rcmscriptname postremove resourcename
rcmscriptname undoremove resourcename
DESCRIPTION
Reconfiguration and Coordination Manager (RCM) is a frame-
work 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 fol-
lows:
[args ...]
SunOS 5.11 Last change: 18 Feb 2003 1
File Formats rcmscript(4)
Every script must implement the following RCM commands:
scriptinfo Get script information.
register Register devices the script handles.
resourceinfo Get resource information.
A script might include some or all the of the following com-
mands:
queryremove Queries whether the resource can be released.
preremove Releases the resource.
postremove Provides post-resource removal notification.
undoremove Undo the actions done in preremove.
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 COMANDS section
for a detailed description of the commands.
1. Prior to removing the resource from the system dur-
ing DR, the script's queryremove command is run:
queryremove
The script should check for obvious reasons why the
resource can not be removed from the perspective of
its service or application.
2. If the script indicates that the resource can be
removed in the queryremove command. The script's
preremove command is run:
SunOS 5.11 Last change: 18 Feb 2003 2
File Formats rcmscript(4)
preremove
The script releases the resource from the service
or application represented by the script and
prepares for the resource removal. Releasing the
resource includes closing the resource if the
resource is currently opened by its application.
3. The system then proceeds to remove the resource.
4. If the system has removed the resource successfully
the script's postremove command is run:
postremove
Otherwise the script's undoremove command is run:
undoremove
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:
o Takes RCM command and additional arguments from the
command line and environment parameters.
o Processes the command.
o Writes the expected return data to stdout as
name=value pairs delimited by newlines, where name
is the name of the return data item that RCM
expects and value is the value associated with the
data item.
Environment
The initial environment of RCM scripts is set as follows:
o Process UID is set to the UID of the script.
o Process GID is set to the GID of the script.
o PATH variable is set to /usr/sbin:/usr/bin.
o Current working directory is set to:
SunOS 5.11 Last change: 18 Feb 2003 3
File Formats rcmscript(4)
o /var/run for scripts owned by root
o /tmp for scripts not owned by root
o File descriptor 0 (stdin) is set to /dev/null
o Environment variable RCMENVDEBUGLEVEL is set to
the debug level. Logging is discussed below.
o The following environment variables are also set
where possible:
o LANG
o LCOLATE
o LCTYPE
o LCMESAGES
o LCMONETARY
o LCNUMERIC
o LCTIME
o LCAL
o TZ
See environ(5) for a description of these variables. See
gettext(1) for details on retrieving localized messages.
All environment variable names beginning with RCMENV 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 ASCI unless the controlling environment
variables are specified otherwise.
Commands
scriptinfo
The scriptinfo command is invoked to gather information
about the script.
Return data: If successful, the script must write the
following name-value pairs to stdout and
exit with status 0:
o rcmscriptversion=1
SunOS 5.11 Last change: 18 Feb 2003 4
File Formats rcmscript(4)
o rcmscriptfuncinfo=scriptfuncinfo
o rcmcmdtimeout=commandtimeoutvalue
where scriptfuncinfo is a localized
human-readable message describing the func-
tionality of the script.
The RCM monitors the execution time of RCM
commands by RCM scripts.
commandtimeoutvalue is the maximum time in
seconds the script is expected to take to
process any RCM command except the scrip-
tinfo command itself. If an RCM script does
not process the RCM command and exit within
this time, RCM sends a SIGABRT signal to the
script process. RCM then waits for a few
seconds for the script to finish the pro-
cessing of the current RCM command and exit.
If the script does not exit within this
time, RCM sends a SIGKIL signal to the
script.
The rcmcmdtimeout name-value pair is
optional. It is only needed if the script is
expected to take more than a few seconds to
process any RCM command. Setting this name
to a value of 0 (zero) disables the timer.
If this name-value pair is not supplied, a
default value is assigned by the RCM.
Upon failure, the script must specify the
failure reason using the name-value pair
rcmfailurereason and exit with status 1.
register
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
rcmresourcename.
Return Data: If successful, the script must write the
following name-value pairs to stdout and
exit with status 0:
rcmresourcename=resourcename
rcmresourcename=resourcename
.
.
.
SunOS 5.11 Last change: 18 Feb 2003 5
File Formats rcmscript(4)
where resourcename is the name of the
resource the script is interested in.
Upon failure, the script must specify the
failure reason using the name-value pair
rcmfailurereason and exit with status 1.
resourceinfo resourcename
The resourceinfo command is invoked to get the usage infor-
mation about resourcename.
Return Data: If successful, the script must write the
following name-value pair to stdout and exit
with status 0:
rcmresourceusageinfo=resourceusage
where resourceusage is a localized human
readable message describing the usage of the
resource by the script.
Upon failure, the script must specify the
failure reason using the name-value pair
rcmfailurereason and exit with status 1.
queryremove resourcename
Prior to removing the resource from the system, the
queryremove command is invoked to query the script to deter-
mine whether the script can release the given resource suc-
cessfully 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:
RCMENVFORCE Can be one of:
FALSE Normal request.
TRUE Request is urgent. The script
should check whether the resource
can be released successfully by
force, such as by using the force
option to unmount a file system.
SunOS 5.11 Last change: 18 Feb 2003 6
File Formats rcmscript(4)
Return Data: If the command succeeds, the script must
return no data and exit with status 0.
If the script would not be able to release
the resource, it must specify the reason
using the name-value pair rcmfailurereason
and exit with status 3.
Upon any other failure, the script must
specify the failure reason using the name-
value pair rcmfailurereason and exit with
status 1.
preremove resourcename
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 clos-
ing 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:
RCMENVFORCE Can be one of:
FALSE Normal request.
TRUE Request is urgent. The script
should make extra effort to
release the resource, such as by
using the force option to unmount
a file system.
Return Data: If the command succeeds, the script must
return no data and exit with status 0.
If the script cannot release the resource,
it must specify the reason using the name-
value pair rcmfailurereason and exit with
status 3.
Upon any other failure, the script must
specify the failure reason using the name-
value pair rcmfailurereason and exit with
status 1.
SunOS 5.11 Last change: 18 Feb 2003 7
File Formats rcmscript(4)
postremove resourcename
The postremove command is invoked after the given resour-
cename has been removed.
Return Data: If the command succeeds, the script must
return no data and exit with status 0.
Upon failure, the script must specify the
failure reason using the name-value pair
rcmfailurereason and exit with status 1.
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 com-
mand for that resource.
Return Data: If the command succeeds, the script must
return no data and exit with status 0.
Upon failure, the script must specify the
failure reason using the name-value pair
rcmfailurereason and exit with status 1.
Logging
A script must log all error and debug messages by writing to
stdout the name-value pairs listed below. The logged mes-
sages go to syslogd(1M) with the syslog facility of
LOGDAEMON. See syslog.conf(4).
rcmlogerr=message Logs the message with the syslog
level of LOGER.
rcmlogwarn=message Logs the message with the syslog
level of LOGWARNING.
rcmloginfo=message Logs the message with the syslog
level of LOGINFO.
rcmlogdebug=message Logs the message with the syslog
level of LOGDEBUG.
SunOS 5.11 Last change: 18 Feb 2003 8
File Formats rcmscript(4)
A script can use the environment variable
RCMENVDEBUGLEVEL to control the amount of information to
log. RCMENVDEBUGLEVEL is a numeric value ranging from 0
to 9, with 0 meaning log the least amount of information and
9 meaning log the most.
Installing or Removing RCM Scripts
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
Scripts for specific systems
/usr/platform/`uname -i`/lib/rcm/scripts
Scripts for specific hardware implementation
/usr/platform/`uname -m`/lib/rcm/scripts
Scripts for specific hardware class
/usr/lib/rcm/scripts
Scripts for any hardware
Installing a Script
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 rcmdaemon. For example:
SunOS 5.11 Last change: 18 Feb 2003 9
File Formats rcmscript(4)
# cp SUNW,sample.pl /usr/lib/rcm/scripts
# chown user[:group] /usr/lib/rcm/scripts/SUNW,sample.pl
# pkill -HUP -x -u root rcmdaemon
Removing a script
Remove the script from the appropriate directory from the
list above and send SIGHUP to rcmdaemon. For example:
# rm /usr/lib/rcm/scripts/SUNW,sample.pl
# pkill -HUP -x -u root rcmdaemon
EXAMPLES
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 (RCMENVFORCE=FALSE) it indicates that it cannot release
# the tape drive with appropriate error message. When forced
# (RCMENVFORCE=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" => doscriptinfo,
"register" => doregister,
SunOS 5.11 Last change: 18 Feb 2003 10
File Formats rcmscript(4)
"resourceinfo" => doresourceinfo,
"queryremove" => dopreremove,
"preremove" => dopreremove
);
if (defined($dispatch{$cmd})) {
&{$dispatch{$cmd}};
} else {
exit (2);
}
sub doscriptinfo
{
print "rcmscriptversion=1\n";
print "rcmscriptfuncinfo=Tape backup appl script for DR\n";
exit (0);
}
sub doregister
{
my ($dir, $f, $errmsg);
$dir = opendir(RMT, "/dev/rmt");
if (!$dir) {
$errmsg = "Unable to open /dev/rmt directory: $!";
print "rcmfailurereason=$errmsg\n";
exit (1);
}
while ($f = readdir(RMT)) {
# ignore hidden files and multiple names for the same device
if (($f !~ /^./) && ($f =~ /^[0-9]$/)) {
print "rcmresourcename=/dev/rmt/$f\n";
}
}
closedir(RMT);
exit (0);
}
sub doresourceinfo
{
my ($rsrc, $unit);
$rsrc = shift(@ARGV);
if ($rsrc =~ /^/dev/rmt/([0-9])$/) {
$unit = $1;
print "rcmresourceusageinfo=Backup Tape Unit Number $unit\n";
exit (0);
} else {
print "rcmfailurereason=Unknown tape device!\n";
SunOS 5.11 Last change: 18 Feb 2003 11
File Formats rcmscript(4)
exit (1);
}
}
sub dopreremove
{
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 RCMENVFORCE is FALSE deny the operation.
# If RCMENVFORCE is TRUE kill the backup application in order
# to allow the DR operation to proceed
#
if ($ENV{RCMENVFORCE} 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 "rcmfailurereason=tape backup in progress pid=...\n";
exit (3);
}
}
EXIT STATUS
A script must exit with following exit status values:
0 Operation specified by the given RCM command has been
executed successfully by the script. For queryremove
command it also means that the script can successfully
release the resource.
1 An error occurred while processing the RCM command. The
script should provide the error message to RCM using
the name-value pair rcmfailurereason before exiting.
SunOS 5.11 Last change: 18 Feb 2003 12
File Formats rcmscript(4)
2 The script does not support the given RCM command. A
script must exit with this status if it cannot under-
stand the given RCM command.
3 Indicates that the script cannot release the resource
for preremove and queryremove commands. The script
should provide a message to RCM specifying the reason
for not being able to release the resource using the
name-value pair rcmfailurereason before exiting.
ERORS
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.
rcmfailurereason=failurereason
where failurereason is a localized human readable message
describing the reason for failure of the RCM command.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Evolving
SEE ALSO
gettext(1), cfgadm(1M), cfgadmscsi(1M), cfgadmpci(1M),
syslog(3C), signal.h(3HEAD), syslog.conf(4), attributes(5),
environ(5)
NOTES
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.
SunOS 5.11 Last change: 18 Feb 2003 13
File Formats rcmscript(4)
RCM commands are invoked only for the resources whose sub-
systems participate within the RCM framework. Currently, not
all susbsystems participate within the RCM framework.
SunOS 5.11 Last change: 18 Feb 2003 14
|
