1rcmscript(4) File Formats rcmscript(4)
2
6 rcmscript - script interface specification for the Reconfiguration and
7 Coordination Manager
8
10 rcm_scriptname scriptinfo
11 rcm_scriptname register
14 rcm_scriptname resourceinfo resourcename
17 rcm_scriptname queryremove resourcename
20 rcm_scriptname preremove resourcename
23 rcm_scriptname postremove resourcename
26 rcm_scriptname undoremove resourcename
29
32 Reconfiguration and Coordination Manager (RCM) is a framework designed
33 to coordinate device consumers during Solaris Dynamic Reconfiguration
34 (DR). The interfaces specified in this man page allow device consumers,
35 such as application vendors or site administrators, to act before and
36 after DR operations take place by providing RCM scripts. You can write
37 your own RCM scripts to shut down your applications, or to cleanly
38 release the devices from your applications during dynamic remove opera‐
39 tions.
40 An RCM script is an executable perl script, a shell script or a binary.
43 Perl is the recommended language. Each script is run in its own address
44 space using the user-id of the script file owner.
45 An RCM script is invoked on demand in response to DR as follows:
48 <scriptname> <command> [args ...]
50 Every script must implement the following RCM commands:
55 scriptinfo Get script information.
57 register Register devices the script handles.
60 resourceinfo Get resource information.
63 A script might include some or all the of the following commands:
67 queryremove Queries whether the resource can be released.
69 preremove Releases the resource.
72 postremove Provides post-resource removal notification.
75 undoremove Undo the actions done in preremove.
78 When a script's register command is run, the script should supply, in
82 return data, all resource names the script or its application handles
83 that could potentially be removed by DR. A resource name refers to a
84 name in /dev path name.
85 Below is a high-level overview of the sequence of script invocations
88 that occurs when dynamic removal of a script's registered resource is
89 attempted. See the COMMANDS section for a detailed description of the
90 commands.
91 1. Prior to removing the resource from the system during DR,
93 the script's queryremove command is run:
94 <scriptname> queryremove <resourcename>
96 The script should check for obvious reasons why the resource
99 can not be removed from the perspective of its service or
100 application.
101 2. If the script indicates that the resource can be removed in
103 the queryremove command. The script's preremove command is
104 run:
105 <scriptname> preremove <resourcename>
107 The script releases the resource from the service or appli‐
110 cation represented by the script and prepares for the
111 resource removal. Releasing the resource includes closing
112 the resource if the resource is currently opened by its
113 application.
114 3. The system then proceeds to remove the resource.
116 4. If the system has removed the resource successfully the
118 script's postremove command is run:
119 <scriptname> postremove <resourcename>
121 Otherwise the script's undoremove command is run:
124 <scriptname> undoremove <resourcename>
126 For any commands the script does not implement, it must exit with exit
131 status of 2. RCM silently returns success for the script's unimple‐
132 mented commands.
133 A script performs the following basic steps:
136 o Takes RCM command and additional arguments from the command
138 line and environment parameters.
139 o Processes the command.
141 o Writes the expected return data to stdout as name=value
143 pairs delimited by newlines, where name is the name of the
144 return data item that RCM expects and value is the value
145 associated with the data item.
146 Environment
148 The initial environment of RCM scripts is set as follows:
149 o Process UID is set to the UID of the script.
151 o Process GID is set to the GID of the script.
153 o PATH variable is set to /usr/sbin:/usr/bin.
155 o Current working directory is set to:
157 o /var/run for scripts owned by root
159 o /tmp for scripts not owned by root
161 o File descriptor 0 (stdin) is set to /dev/null
163 o Environment variable RCM_ENV_DEBUG_LEVEL is set to the debug
165 level. Logging is discussed below.
166 o
168 The following environment variables are also set where pos‐
169 sible:
170 o LANG
172 o LC_COLLATE
174 o LC_CTYPE
176 o LC_MESSAGES
178 o LC_MONETARY
180 o LC_NUMERIC
182 o LC_TIME
184 o LC_ALL
186 o TZ
188 See environ(5) for a description of these variables. See gettext(1)
189 for details on retrieving localized messages.
190 All environment variable names beginning with RCM_ENV_ are reserved for
193 use by the RCM.
194 The character encoding used by the RCM and RCM scripts to exchange RCM
197 commands, environment parameters, and name-value pairs is ASCII unless
198 the controlling environment variables are specified otherwise.
199 Commands
201 scriptinfo
202 The scriptinfo command is invoked to gather information about the
203 script.
204 Return data: If successful, the script must write the following
206 name-value pairs to stdout and exit with status 0:
207 o rcm_script_version=1
209 o rcm_script_func_info=script_func_info
211 o rcm_cmd_timeout=command_timeout_value
213 where script_func_info is a localized human-readable
214 message describing the functionality of the script.
215 The RCM monitors the execution time of RCM commands by
217 RCM scripts. command_timeout_value is the maximum time
218 in seconds the script is expected to take to process
219 any RCM command except the scriptinfo command itself.
220 If an RCM script does not process the RCM command and
221 exit within this time, RCM sends a SIGABRT signal to
222 the script process. RCM then waits for a few seconds
223 for the script to finish the processing of the current
224 RCM command and exit. If the script does not exit
225 within this time, RCM sends a SIGKILL signal to the
226 script.
227 The rcm_cmd_timeout name-value pair is optional. It is
229 only needed if the script is expected to take more than
230 a few seconds to process any RCM command. Setting this
231 name to a value of 0 (zero) disables the timer. If this
232 name-value pair is not supplied, a default value is
233 assigned by the RCM.
234 Upon failure, the script must specify the failure rea‐
236 son using the name-value pair rcm_failure_reason and
237 exit with status 1.
238 register
241 The register command is invoked to allow a script to specify the
242 resources that it or its application handles that could potentially be
243 removed by DR. The script has to supply all its resource names to RCM
244 using the name-value pair rcm_resource_name.
245 Return Data: If successful, the script must write the following
247 name-value pairs to stdout and exit with status 0:
248 rcm_resource_name=resourcename
250 rcm_resource_name=resourcename
251 .
252 .
253 .
254 where resourcename is the name of the resource the
257 script is interested in.
258 Upon failure, the script must specify the failure rea‐
260 son using the name-value pair rcm_failure_reason and
261 exit with status 1.
262 resourceinfo resourcename
265 The resourceinfo command is invoked to get the usage information about
266 resourcename.
267 Return Data: If successful, the script must write the following
269 name-value pair to stdout and exit with status 0:
270 rcm_resource_usage_info=resource_usage
272 where resource_usage is a localized human readable mes‐
275 sage describing the usage of the resource by the
276 script.
277 Upon failure, the script must specify the failure rea‐
279 son using the name-value pair rcm_failure_reason and
280 exit with status 1.
281 queryremove resourcename
284 Prior to removing the resource from the system, the queryremove command
285 is invoked to query the script to determine whether the script can
286 release the given resource successfully from the service or application
287 it represents. The script does not actually release the resource. The
288 script might indicate that it is not able to release the resource if
289 the resource is critical for its service or application.
290 Additional environment parameter:
293 RCM_ENV_FORCE Can be one of:
295 FALSE Normal request.
297 TRUE Request is urgent. The script should check
300 whether the resource can be released success‐
301 fully by force, such as by using the force
302 option to unmount a file system.
303 Return Data: If the command succeeds, the script must return no data
307 and exit with status 0.
308 If the script would not be able to release the
310 resource, it must specify the reason using the name-
311 value pair rcm_failure_reason and exit with status 3.
312 Upon any other failure, the script must specify the
314 failure reason using the name-value pair rcm_fail‐
315 ure_reason and exit with status 1.
316 preremove resourcename
319 The preremove command is invoked prior to an attempt to remove the
320 given resourcename. In response to this command the script can either
321 release the resource (including closing the device if the device is
322 currently opened) from the service or application it represents or
323 indicate that it can not release the resource if the resource is criti‐
324 cal for its service or application.
325 Additional environment parameter:
328 RCM_ENV_FORCE Can be one of:
330 FALSE Normal request.
332 TRUE Request is urgent. The script should make
335 extra effort to release the resource, such as
336 by using the force option to unmount a file
337 system.
338 Return Data: If the command succeeds, the script must return no data
342 and exit with status 0.
343 If the script cannot release the resource, it must
345 specify the reason using the name-value pair rcm_fail‐
346 ure_reason and exit with status 3.
347 Upon any other failure, the script must specify the
349 failure reason using the name-value pair rcm_fail‐
350 ure_reason and exit with status 1.
351 postremove resourcename
354 The postremove command is invoked after the given resourcename has been
355 removed.
356 Return Data: If the command succeeds, the script must return no data
358 and exit with status 0.
359 Upon failure, the script must specify the failure rea‐
361 son using the name-value pair rcm_failure_reason and
362 exit with status 1.
363 undoremove resourcename
367 The undoremove command is invoked to undo what was done in the previous
370 preremove command for the given resourcename. The script can bring the
371 state of the resource to the same state it was in when the script
372 received the preremove command for that resource.
373 Return Data: If the command succeeds, the script must return no data
375 and exit with status 0.
376 Upon failure, the script must specify the failure rea‐
378 son using the name-value pair rcm_failure_reason and
379 exit with status 1.
380 Logging
383 A script must log all error and debug messages by writing to stdout the
384 name-value pairs listed below. The logged messages go to syslogd(1M)
385 with the syslog facility of LOG_DAEMON. See syslog.conf(4).
386 rcm_log_err=message Logs the message with the syslog level of
388 LOG_ERR.
389 rcm_log_warn=message Logs the message with the syslog level of
392 LOG_WARNING.
393 rcm_log_info=message Logs the message with the syslog level of
396 LOG_INFO.
397 rcm_log_debug=message Logs the message with the syslog level of
400 LOG_DEBUG.
401 A script can use the environment variable RCM_ENV_DEBUG_LEVEL to con‐
405 trol the amount of information to log. RCM_ENV_DEBUG_LEVEL is a numeric
406 value ranging from 0 to 9, with 0 meaning log the least amount of
407 information and 9 meaning log the most.
408 Installing or Removing RCM Scripts
410 You must use the following format to name a script:
411 vendor,service
413 where vendor is the stock symbol (or any distinctive name) of the ven‐
418 dor providing the script and service is the name of service the script
419 represents.
420 You must be a superuser (root) to install or remove an RCM script.
423 Select one of the following directories where you want to place the
426 script:
427 /etc/rcm/scripts
429 Scripts for specific systems
431 /usr/platform/`uname -i`/lib/rcm/scripts
434 Scripts for specific hardware implementation
436 /usr/platform/`uname -m`/lib/rcm/scripts
439 Scripts for specific hardware class
441 /usr/lib/rcm/scripts
444 Scripts for any hardware
446 Installing a Script
449 To install a script, copy the script to the appropriate directory from
450 the list above, change the userid and the groupid of the script to the
451 desired values, and send SIGHUP to rcm_daemon. For example:
452 # cp SUNW,sample.pl /usr/lib/rcm/scripts
454 # chown user[:group] /usr/lib/rcm/scripts/SUNW,sample.pl
455 # pkill -HUP -x -u root rcm_daemon
456 Removing a script
460 Remove the script from the appropriate directory from the list above
461 and send SIGHUP to rcm_daemon. For example:
462 # rm /usr/lib/rcm/scripts/SUNW,sample.pl
464 # pkill -HUP -x -u root rcm_daemon
465
469 Example 1 Site Customization RCM Script
470 #! /usr/bin/perl -w
472 #
474 # A sample site customization RCM script for a tape backup application.
475 #
476 # This script registers all tape drives in the system with RCM.
477 # When the system attempts to remove a tape drive by DR the script
478 # does the following:
479 # - if the tape drive is not being used for backup, it allows the
480 # DR to continue.
481 # - if the tape drive is being used for backup, and when DR is not
482 # forced (RCM_ENV_FORCE=FALSE) it indicates that it cannot release
483 # the tape drive with appropriate error message. When forced
484 # (RCM_ENV_FORCE=TRUE) it kills the tape backup application in
485 # order to allow the DR to continue.
486 #
487 # This script does not implement the postremove and undoremove commands
488 # since there is nothing to cleanup after DR remove operation is
489 # completed or failed. If any cleanup is needed after the DR removal
490 # completed, postremove command needs to implemented. If any cleanup is
491 # needed in the event of DR removal failure, undoremove command needs
492 # to be implemented.
493 #
494 use strict;
496 my ($cmd, %dispatch);
498 $cmd = shift(@ARGV);
500 # dispatch table for RCM commands
502 %dispatch = (
503 "scriptinfo" => do_scriptinfo,
504 "register" => do_register,
505 "resourceinfo" => do_resourceinfo,
506 "queryremove" => do_preremove,
507 "preremove" => do_preremove
508 );
509 if (defined($dispatch{$cmd})) {
511 &{$dispatch{$cmd}};
512 } else {
513 exit (2);
514 }
515 sub do_scriptinfo
517 {
518 print "rcm_script_version=1\n";
519 print "rcm_script_func_info=Tape backup appl script for DR\n";
520 exit (0);
521 }
522 sub do_register
524 {
525 my ($dir, $f, $errmsg);
526 $dir = opendir(RMT, "/dev/rmt");
528 if (!$dir) {
529 $errmsg = "Unable to open /dev/rmt directory: $!";
530 print "rcm_failure_reason=$errmsg\n";
531 exit (1);
532 }
533 while ($f = readdir(RMT)) {
535 # ignore hidden files and multiple names for the same device
536 if (($f !~ /^./) && ($f =~ /^[0-9]+$/)) {
537 print "rcm_resource_name=/dev/rmt/$f\n";
538 }
539 }
541 closedir(RMT);
543 exit (0);
544 }
545 sub do_resourceinfo
547 {
548 my ($rsrc, $unit);
549 $rsrc = shift(@ARGV);
551 if ($rsrc =~ /^devrmt([0-9]+)$/) {
552 $unit = $1;
553 print "rcm_resource_usage_info=Backup Tape Unit Number $unit\n";
554 exit (0);
555 } else {
556 print "rcm_failure_reason=Unknown tape device!\n";
557 exit (1);
558 }
559 }
560 sub do_preremove
562 {
563 my ($rsrc);
564 $rsrc = shift(@ARGV);
566 # check if backup application is using this resource
568 # if (the backup application is not running on $rsrc) {
569 # allow the DR to continue
570 # exit (0);
571 #}
572 #
573 # If RCM_ENV_FORCE is FALSE deny the operation.
574 # If RCM_ENV_FORCE is TRUE kill the backup application in order
575 # to allow the DR operation to proceed
576 #
577 if ($ENV{RCM_ENV_FORCE} eq 'TRUE') {
578 if ($cmd eq 'preremove') {
579 # kill the tape backup application
580 }
581 exit (0);
582 } else {
583 #
584 # indicate that the tape drive can not be released
585 # since the device is being used for backup by the
586 # tape backup application
587 #
588 print "rcm_failure_reason=tape backup in progress pid=...\n";
589 exit (3);
590 }
592 }
593
596 A script must exit with following exit status values:
597 0 Operation specified by the given RCM command has been executed
599 successfully by the script. For queryremove command it also means
600 that the script can successfully release the resource.
601 1 An error occurred while processing the RCM command. The script
604 should provide the error message to RCM using the name-value pair
605 rcm_failure_reason before exiting.
606 2 The script does not support the given RCM command. A script must
609 exit with this status if it cannot understand the given RCM com‐
610 mand.
611 3 Indicates that the script cannot release the resource for prere‐
614 move and queryremove commands. The script should provide a message
615 to RCM specifying the reason for not being able to release the
616 resource using the name-value pair rcm_failure_reason before exit‐
617 ing.
618
621 If a script cannot successfully process an RCM command, it must supply
622 to the RCM a message indicating the reason for failure by writing a
623 name-value pair, in the form shown below, to stdout and exiting with
624 the appropriate exit status.
625 rcm_failure_reason=failure_reason
627 where failure_reason is a localized human readable message describing
632 the reason for failure of the RCM command.
633
635 See attributes(5) for descriptions of the following attributes:
636 ┌─────────────────────────────┬─────────────────────────────┐
641 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
642 ├─────────────────────────────┼─────────────────────────────┤
643 │Interface Stability │Evolving │
644 └─────────────────────────────┴─────────────────────────────┘
645
647 gettext(1), cfgadm(1M), cfgadm_scsi(1M), cfgadm_pci(1M), syslog(3C),
648 signal.h(3HEAD), syslog.conf(4), attributes(5), environ(5)
649
651 RCM scripts are expected to properly handle all RCM commands that the
652 script implements and to log all errors. Only root has permission to
653 add or remove an RCM script. An ill-behaved RCM script can cause unex‐
654 pected DR failures.
655 RCM commands are invoked only for the resources whose subsystems par‐
658 ticipate within the RCM framework. Currently, not all susbsystems par‐
659 ticipate within the RCM framework.
660SunOS 5.11 18 Feb 2003 rcmscript(4)