usr/src/man/man4/rcmscript.4

   1 '\" te
   2 .\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH RCMSCRIPT 4 "Feb 18, 2003"
   7 .SH NAME
   8 rcmscript \- script interface specification for the Reconfiguration and
   9 Coordination Manager
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fB\fIrcm_scriptname\fR scriptinfo\fR
  14 .fi
  15
  16 .LP
  17 .nf
  18 \fB\fIrcm_scriptname\fR register\fR
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fB\fIrcm_scriptname\fR resourceinfo \fIresourcename\fR\fR
  24 .fi
  25
  26 .LP
  27 .nf
  28 \fB\fIrcm_scriptname\fR queryremove \fIresourcename\fR\fR
  29 .fi
  30
  31 .LP
  32 .nf
  33 \fB\fIrcm_scriptname\fR preremove \fIresourcename\fR\fR
  34 .fi
  35
  36 .LP
  37 .nf
  38 \fB\fIrcm_scriptname\fR postremove \fIresourcename\fR\fR
  39 .fi
  40
  41 .LP
  42 .nf
  43 \fB\fIrcm_scriptname\fR undoremove \fIresourcename\fR\fR
  44 .fi
  45
  46 .SH DESCRIPTION
  47 .LP
  48 Reconfiguration and Coordination Manager (RCM) is a framework designed to
  49 coordinate device consumers during Solaris Dynamic Reconfiguration (DR). The
  50 interfaces specified in this man page allow device consumers, such as
  51 application vendors or site administrators, to act before and after DR
  52 operations take place by providing RCM scripts. You can write your own RCM
  53 scripts to shut down your applications, or to cleanly release the devices from
  54 your applications during dynamic remove operations.
  55 .sp
  56 .LP
  57 An RCM script is an executable perl script, a shell script or a binary. Perl is
  58 the recommended language. Each script is run in its own address space using the
  59 user-id of the script file owner.
  60 .sp
  61 .LP
  62 An RCM script is invoked on demand in response to DR as follows:
  63 .sp
  64 .in +2
  65 .nf
  66 \fI<scriptname>\fR \fI<command>\fR [\fIargs\fR ...]
  67 .fi
  68 .in -2
  69 .sp
  70
  71 .sp
  72 .LP
  73 Every script must implement the following RCM commands:
  74 .sp
  75 .ne 2
  76 .na
  77 \fB\fBscriptinfo\fR\fR
  78 .ad
  79 .RS 16n
  80 Get script information.
  81 .RE
  82
  83 .sp
  84 .ne 2
  85 .na
  86 \fB\fBregister\fR\fR
  87 .ad
  88 .RS 16n
  89 Register devices the script handles.
  90 .RE
  91
  92 .sp
  93 .ne 2
  94 .na
  95 \fB\fBresourceinfo\fR\fR
  96 .ad
  97 .RS 16n
  98 Get resource information.
  99 .RE
 100
 101 .sp
 102 .LP
 103 A script might include some or all the of the following commands:
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fBqueryremove\fR\fR
 108 .ad
 109 .RS 15n
 110 Queries whether the resource can be released.
 111 .RE
 112
 113 .sp
 114 .ne 2
 115 .na
 116 \fB\fBpreremove\fR\fR
 117 .ad
 118 .RS 15n
 119 Releases the resource.
 120 .RE
 121
 122 .sp
 123 .ne 2
 124 .na
 125 \fB\fBpostremove\fR\fR
 126 .ad
 127 .RS 15n
 128 Provides post-resource removal notification.
 129 .RE
 130
 131 .sp
 132 .ne 2
 133 .na
 134 \fB\fBundoremove\fR\fR
 135 .ad
 136 .RS 15n
 137 Undo the actions done in preremove.
 138 .RE
 139
 140 .sp
 141 .LP
 142 When a script's \fBregister\fR command is run, the script should supply, in
 143 return data, all resource names the script or its application handles that
 144 could potentially be removed by DR. A resource name refers to a name in
 145 \fB/dev\fR path name.
 146 .sp
 147 .LP
 148 Below is a high-level overview of the sequence of script invocations that
 149 occurs when dynamic removal of a script's registered resource is attempted. See
 150 the COMMANDS section for a detailed description of the commands.
 151 .RS +4
 152 .TP
 153 1.
 154 Prior to removing the resource from the system during DR, the script's
 155 \fBqueryremove\fR command is run:
 156 .sp
 157 .in +2
 158 .nf
 159 \fI<scriptname>\fR queryremove \fI<resourcename>\fR
 160 .fi
 161 .in -2
 162 .sp
 163
 164 The script should check for obvious reasons why the resource can not be removed
 165 from the perspective of its service or application.
 166 .RE
 167 .RS +4
 168 .TP
 169 2.
 170 If the script indicates that the resource can be removed in the
 171 \fBqueryremove\fR command. The script's \fBpreremove\fR command is run:
 172 .sp
 173 .in +2
 174 .nf
 175 \fI<scriptname>\fR preremove \fI<resourcename>\fR
 176 .fi
 177 .in -2
 178 .sp
 179
 180 The script releases the resource from the service or application represented by
 181 the script and prepares for the resource removal. Releasing the resource
 182 includes closing the resource if the resource is currently opened by its
 183 application.
 184 .RE
 185 .RS +4
 186 .TP
 187 3.
 188 The system then proceeds to remove the resource.
 189 .RE
 190 .RS +4
 191 .TP
 192 4.
 193 If the system has removed the resource successfully the script's
 194 \fBpostremove\fR command is run:
 195 .sp
 196 .in +2
 197 .nf
 198 \fI<scriptname>\fR postremove \fI<resourcename>\fR
 199 .fi
 200 .in -2
 201 .sp
 202
 203 Otherwise the script's \fBundoremove\fR command is run:
 204 .sp
 205 .in +2
 206 .nf
 207 \fI<scriptname>\fR undoremove \fI<resourcename>\fR
 208 .fi
 209 .in -2
 210 .sp
 211
 212 .RE
 213 .sp
 214 .LP
 215 For any commands the script does not implement, it must exit with exit status
 216 of 2. RCM silently returns success for the script's unimplemented commands.
 217 .sp
 218 .LP
 219 A script performs the following basic steps:
 220 .RS +4
 221 .TP
 222 .ie t \(bu
 223 .el o
 224 Takes RCM command and additional arguments from the command line and
 225 environment parameters.
 226 .RE
 227 .RS +4
 228 .TP
 229 .ie t \(bu
 230 .el o
 231 Processes the command.
 232 .RE
 233 .RS +4
 234 .TP
 235 .ie t \(bu
 236 .el o
 237 Writes the expected return data to stdout as \fIname=value\fR pairs delimited
 238 by newlines, where \fIname\fR is the name of the return data item that RCM
 239 expects and \fIvalue\fR is the value associated with the data item.
 240 .RE
 241 .SS "Environment"
 242 .LP
 243 The initial environment of RCM scripts is set as follows:
 244 .RS +4
 245 .TP
 246 .ie t \(bu
 247 .el o
 248 Process UID is set to the UID of the script.
 249 .RE
 250 .RS +4
 251 .TP
 252 .ie t \(bu
 253 .el o
 254 Process GID is set to the GID of the script.
 255 .RE
 256 .RS +4
 257 .TP
 258 .ie t \(bu
 259 .el o
 260 \fBPATH\fR variable is set to \fB/usr/sbin:/usr/bin\fR.
 261 .RE
 262 .RS +4
 263 .TP
 264 .ie t \(bu
 265 .el o
 266 Current working directory is set to:
 267 .RS +4
 268 .TP
 269 .ie t \(bu
 270 .el o
 271 \fB/var/run\fR for scripts owned by root
 272 .RE
 273 .RS +4
 274 .TP
 275 .ie t \(bu
 276 .el o
 277 \fB/tmp\fR for scripts not owned by root
 278 .RE
 279 .RE
 280 .RS +4
 281 .TP
 282 .ie t \(bu
 283 .el o
 284 File descriptor 0 (stdin) is set to \fB/dev/null\fR
 285 .RE
 286 .RS +4
 287 .TP
 288 .ie t \(bu
 289 .el o
 290 Environment variable \fBRCM_ENV_DEBUG_LEVEL\fR is set to the debug level.
 291 Logging is discussed below.
 292 .RE
 293 .RS +4
 294 .TP
 295 .ie t \(bu
 296 .el o
 297  The following environment variables are also set where possible:
 298 .RS +4
 299 .TP
 300 .ie t \(bu
 301 .el o
 302 \fBLANG\fR
 303 .RE
 304 .RS +4
 305 .TP
 306 .ie t \(bu
 307 .el o
 308 \fBLC_COLLATE\fR
 309 .RE
 310 .RS +4
 311 .TP
 312 .ie t \(bu
 313 .el o
 314 \fBLC_CTYPE\fR
 315 .RE
 316 .RS +4
 317 .TP
 318 .ie t \(bu
 319 .el o
 320 \fBLC_MESSAGES\fR
 321 .RE
 322 .RS +4
 323 .TP
 324 .ie t \(bu
 325 .el o
 326 \fBLC_MONETARY\fR
 327 .RE
 328 .RS +4
 329 .TP
 330 .ie t \(bu
 331 .el o
 332 \fBLC_NUMERIC\fR
 333 .RE
 334 .RS +4
 335 .TP
 336 .ie t \(bu
 337 .el o
 338 \fBLC_TIME\fR
 339 .RE
 340 .RS +4
 341 .TP
 342 .ie t \(bu
 343 .el o
 344 \fBLC_ALL\fR
 345 .RE
 346 .RS +4
 347 .TP
 348 .ie t \(bu
 349 .el o
 350 \fBTZ\fR
 351 .RE
 352 See \fBenviron\fR(5) for a description of these variables. See \fBgettext\fR(1)
 353 for details on retrieving localized messages.
 354 .RE
 355 .sp
 356 .LP
 357 All environment variable names beginning with \fBRCM_ENV_\fR are reserved for
 358 use by the RCM.
 359 .sp
 360 .LP
 361 The character encoding used by the RCM and RCM scripts to exchange RCM
 362 commands, environment parameters, and name-value pairs is ASCII unless the
 363 controlling environment variables are specified otherwise.
 364 .SS "Commands"
 365 .SS "\fBscriptinfo\fR"
 366 .LP
 367 The \fBscriptinfo\fR command is invoked to gather information about the script.
 368 .sp
 369 .ne 2
 370 .na
 371 \fBReturn data:\fR
 372 .ad
 373 .RS 16n
 374 If successful, the script must write the following name-value pairs to stdout
 375 and exit with status 0:
 376 .RS +4
 377 .TP
 378 .ie t \(bu
 379 .el o
 380 \fBrcm_script_version=1\fR
 381 .RE
 382 .RS +4
 383 .TP
 384 .ie t \(bu
 385 .el o
 386 \fBrcm_script_func_info=\fR\fIscript_func_info\fR
 387 .RE
 388 .RS +4
 389 .TP
 390 .ie t \(bu
 391 .el o
 392 \fBrcm_cmd_timeout=\fR\fIcommand_timeout_value\fR
 393 .RE
 394 where \fIscript_func_info\fR is a localized human-readable message describing
 395 the functionality of the script.
 396 .sp
 397 The RCM monitors the execution time of RCM commands by RCM scripts.
 398 \fIcommand_timeout_value\fR is the maximum time in seconds the script is
 399 expected to take to process any RCM command except the \fBscriptinfo\fR command
 400 itself. If an RCM script does not process the RCM command and exit within this
 401 time, RCM sends a \fBSIGABRT\fR signal to the script process. RCM then waits
 402 for a few seconds for the script to finish the processing of the current RCM
 403 command and exit. If the script does not exit within this time, RCM sends a
 404 \fBSIGKILL\fR signal to the script.
 405 .sp
 406 The \fBrcm_cmd_timeout\fR name-value pair is optional. It is only needed if the
 407 script is expected to take more than a few seconds to process any RCM command.
 408 Setting this name to a value of 0 (zero) disables the timer. If this name-value
 409 pair is not supplied, a default value is assigned by the RCM.
 410 .sp
 411 Upon failure, the script must specify the failure reason using the name-value
 412 pair \fBrcm_failure_reason\fR and exit with status 1.
 413 .RE
 414
 415 .SS "\fBregister\fR"
 416 .LP
 417 The \fBregister\fR command is invoked to allow a script to specify the
 418 resources that it or its application handles that could potentially be removed
 419 by DR. The script has to supply all its resource names to RCM using the
 420 name-value pair \fBrcm_resource_name\fR.
 421 .sp
 422 .ne 2
 423 .na
 424 \fBReturn Data:\fR
 425 .ad
 426 .RS 16n
 427 If successful, the script must write the following name-value pairs to stdout
 428 and exit with status 0:
 429 .sp
 430 .in +2
 431 .nf
 432 rcm_resource_name=\fIresourcename\fR
 433 rcm_resource_name=\fIresourcename\fR
 434            .
 435            .
 436            .
 437 .fi
 438 .in -2
 439 .sp
 440
 441 where \fIresourcename\fR is the name of the resource the script is interested
 442 in.
 443 .sp
 444 Upon failure, the script must specify the failure reason using the name-value
 445 pair \fBrcm_failure_reason\fR and exit with status 1.
 446 .RE
 447
 448 .SS "\fBresourceinfo\fR \fIresourcename\fR"
 449 .LP
 450 The \fBresourceinfo\fR command is invoked to get the usage information about
 451 \fIresourcename\fR.
 452 .sp
 453 .ne 2
 454 .na
 455 \fBReturn Data:\fR
 456 .ad
 457 .RS 16n
 458 If successful, the script must write the following name-value pair to stdout
 459 and exit with status 0:
 460 .sp
 461 .in +2
 462 .nf
 463 rcm_resource_usage_info=\fIresource_usage\fR
 464 .fi
 465 .in -2
 466 .sp
 467
 468 where \fIresource_usage\fR is a localized human readable message describing the
 469 usage of the resource by the script.
 470 .sp
 471 Upon failure, the script must specify the failure reason using the name-value
 472 pair \fBrcm_failure_reason\fR and exit with status 1.
 473 .RE
 474
 475 .SS "\fBqueryremove\fR \fIresourcename\fR"
 476 .LP
 477 Prior to removing the resource from the system, the \fBqueryremove\fR command
 478 is invoked to query the script to determine whether the script can release the
 479 given resource successfully from the service or application it represents. The
 480 script does not actually release the resource. The script might indicate that
 481 it is not able to release the resource if the resource is critical for its
 482 service or application.
 483 .sp
 484 .LP
 485 Additional environment parameter:
 486 .sp
 487 .ne 2
 488 .na
 489 \fB\fBRCM_ENV_FORCE\fR\fR
 490 .ad
 491 .RS 17n
 492 Can be one of:
 493 .sp
 494 .ne 2
 495 .na
 496 \fB\fBFALSE\fR\fR
 497 .ad
 498 .RS 9n
 499 Normal request.
 500 .RE
 501
 502 .sp
 503 .ne 2
 504 .na
 505 \fB\fBTRUE\fR\fR
 506 .ad
 507 .RS 9n
 508 Request is urgent. The script should check whether the resource can be released
 509 successfully by force, such as by using the force option to unmount a file
 510 system.
 511 .RE
 512
 513 .RE
 514
 515 .sp
 516 .ne 2
 517 .na
 518 \fBReturn Data:\fR
 519 .ad
 520 .RS 16n
 521 If the command succeeds, the script must return no data and exit with status 0.
 522 .sp
 523 If the script would not be able to release the resource, it must specify the
 524 reason using the name-value pair \fBrcm_failure_reason\fR and exit with status
 525 3.
 526 .sp
 527 Upon any other failure, the script must specify the failure reason using the
 528 name-value pair \fBrcm_failure_reason\fR and exit with status 1.
 529 .RE
 530
 531 .SS "\fBpreremove\fR \fIresourcename\fR"
 532 .LP
 533 The \fBpreremove\fR command is invoked prior to an attempt to remove the given
 534 \fIresourcename\fR. In response to this command the script can either release
 535 the resource (including closing the device if the device is currently opened)
 536 from the service or application it represents or indicate that it can not
 537 release the resource if the resource is critical for its service or
 538 application.
 539 .sp
 540 .LP
 541 Additional environment parameter:
 542 .sp
 543 .ne 2
 544 .na
 545 \fB\fBRCM_ENV_FORCE\fR\fR
 546 .ad
 547 .RS 17n
 548 Can be one of:
 549 .sp
 550 .ne 2
 551 .na
 552 \fB\fBFALSE\fR\fR
 553 .ad
 554 .RS 9n
 555 Normal request.
 556 .RE
 557
 558 .sp
 559 .ne 2
 560 .na
 561 \fB\fBTRUE\fR\fR
 562 .ad
 563 .RS 9n
 564 Request is urgent. The script should make extra effort to release the resource,
 565 such as by using the force option to unmount a file system.
 566 .RE
 567
 568 .RE
 569
 570 .sp
 571 .ne 2
 572 .na
 573 \fBReturn Data:\fR
 574 .ad
 575 .RS 16n
 576 If the command succeeds, the script must return no data and exit with status 0.
 577 .sp
 578 If the script cannot release the resource, it must specify the reason using the
 579 name-value pair \fBrcm_failure_reason\fR and exit with status 3.
 580 .sp
 581 Upon any other failure, the script must specify the failure reason using the
 582 name-value pair \fBrcm_failure_reason\fR and exit with status 1.
 583 .RE
 584
 585 .SS "\fBpostremove\fR \fIresourcename\fR"
 586 .LP
 587 The \fBpostremove\fR command is invoked after the given \fIresourcename\fR has
 588 been removed.
 589 .sp
 590 .ne 2
 591 .na
 592 \fBReturn Data:\fR
 593 .ad
 594 .RS 16n
 595 If the command succeeds, the script must return no data and exit with status 0.
 596 .sp
 597 Upon failure, the script must specify the failure reason using the name-value
 598 pair \fBrcm_failure_reason\fR and exit with status 1.
 599 .RE
 600
 601 .sp
 602 .LP
 603 \fBundoremove\fR \fIresourcename\fR
 604 .sp
 605 .LP
 606 The \fBundoremove\fR command is invoked to undo what was done in the previous
 607 \fBpreremove\fR command for the given \fIresourcename\fR. The script can bring
 608 the state of the resource to the same state it was in when the script received
 609 the \fBpreremove\fR command for that resource.
 610 .sp
 611 .ne 2
 612 .na
 613 \fBReturn Data:\fR
 614 .ad
 615 .RS 16n
 616 If the command succeeds, the script must return no data and exit with status 0.
 617 .sp
 618 Upon failure, the script must specify the failure reason using the name-value
 619 pair \fBrcm_failure_reason\fR and exit with status 1.
 620 .RE
 621
 622 .SS "Logging"
 623 .LP
 624 A script must log all error and debug messages by writing to stdout the
 625 name-value pairs listed below. The logged messages go to \fBsyslogd\fR(1M) with
 626 the \fBsyslog\fR facility of \fBLOG_DAEMON\fR. See \fBsyslog.conf\fR(4).
 627 .sp
 628 .ne 2
 629 .na
 630 \fB\fBrcm_log_err=\fR\fImessage\fR\fR
 631 .ad
 632 .RS 25n
 633 Logs the \fImessage\fR with the syslog level of \fBLOG_ERR\fR.
 634 .RE
 635
 636 .sp
 637 .ne 2
 638 .na
 639 \fB\fBrcm_log_warn=\fR\fImessage\fR\fR
 640 .ad
 641 .RS 25n
 642 Logs the \fImessage\fR with the syslog level of \fBLOG_WARNING\fR.
 643 .RE
 644
 645 .sp
 646 .ne 2
 647 .na
 648 \fB\fBrcm_log_info=\fR\fImessage\fR\fR
 649 .ad
 650 .RS 25n
 651 Logs the \fImessage\fR with the syslog level of \fBLOG_INFO\fR.
 652 .RE
 653
 654 .sp
 655 .ne 2
 656 .na
 657 \fB\fBrcm_log_debug=\fR\fImessage\fR\fR
 658 .ad
 659 .RS 25n
 660 Logs the \fImessage\fR with the syslog level of \fBLOG_DEBUG\fR.
 661 .RE
 662
 663 .sp
 664 .LP
 665 A script can use the environment variable \fBRCM_ENV_DEBUG_LEVEL\fR to control
 666 the amount of information to log. \fBRCM_ENV_DEBUG_LEVEL\fR is a numeric value
 667 ranging from 0 to 9, with 0 meaning log the least amount of information and 9
 668 meaning log the most.
 669 .SS "Installing or Removing RCM Scripts"
 670 .LP
 671 You must use the following format to name a script:
 672 .sp
 673 .in +2
 674 .nf
 675 \fIvendor\fR,\fIservice\fR
 676 .fi
 677 .in -2
 678 .sp
 679
 680 .sp
 681 .LP
 682 where \fIvendor\fR is the stock symbol (or any distinctive name) of the vendor
 683 providing the script and \fIservice\fR is the name of service the script
 684 represents.
 685 .sp
 686 .LP
 687 You must be a superuser (root) to install or remove an RCM script.
 688 .sp
 689 .LP
 690 Select one of the following directories where you want to place the script:
 691 .sp
 692 .ne 2
 693 .na
 694 \fB\fB/etc/rcm/scripts\fR\fR
 695 .ad
 696 .sp .6
 697 .RS 4n
 698 Scripts for specific systems
 699 .RE
 700
 701 .sp
 702 .ne 2
 703 .na
 704 \fB\fB/usr/platform/`uname -i`/lib/rcm/scripts\fR\fR
 705 .ad
 706 .sp .6
 707 .RS 4n
 708 Scripts for specific hardware implementation
 709 .RE
 710
 711 .sp
 712 .ne 2
 713 .na
 714 \fB\fB/usr/platform/`uname -m`/lib/rcm/scripts\fR\fR
 715 .ad
 716 .sp .6
 717 .RS 4n
 718 Scripts for specific hardware class
 719 .RE
 720
 721 .sp
 722 .ne 2
 723 .na
 724 \fB\fB/usr/lib/rcm/scripts\fR\fR
 725 .ad
 726 .sp .6
 727 .RS 4n
 728 Scripts for any hardware
 729 .RE
 730
 731 .SS "Installing a Script"
 732 .LP
 733 To install a script, copy the script to the appropriate directory from the list
 734 above, change the userid and the groupid of the script to the desired values,
 735 and send \fBSIGHUP\fR to \fBrcm_daemon\fR. For example:
 736 .sp
 737 .in +2
 738 .nf
 739 # cp SUNW,sample.pl /usr/lib/rcm/scripts
 740 # chown user[:group] /usr/lib/rcm/scripts/SUNW,sample.pl
 741 # pkill -HUP -x -u root rcm_daemon
 742 .fi
 743 .in -2
 744 .sp
 745
 746 .SS "Removing a script"
 747 .LP
 748 Remove the script from the appropriate directory from the list above and send
 749 \fBSIGHUP\fR to \fBrcm_daemon\fR. For example:
 750 .sp
 751 .in +2
 752 .nf
 753 # rm /usr/lib/rcm/scripts/SUNW,sample.pl
 754 # pkill -HUP -x -u root rcm_daemon
 755 .fi
 756 .in -2
 757 .sp
 758
 759 .SH EXAMPLES
 760 .LP
 761 \fBExample 1 \fRSite Customization RCM Script
 762 .sp
 763 .in +2
 764 .nf
 765 #! /usr/bin/perl -w
 766
 767 #
 768 # A sample site customization RCM script for a tape backup application.
 769 #
 770 # This script registers all tape drives in the system with RCM.
 771 # When the system attempts to remove a tape drive by DR the script
 772 # does the following:
 773 #   - if the tape drive is not being used for backup, it allows the
 774 #     DR to continue.
 775 #   - if the tape drive is being used for backup, and when DR is not
 776 #     forced (RCM_ENV_FORCE=FALSE) it indicates that it cannot release
 777 #     the tape drive with appropriate error message. When forced
 778 #     (RCM_ENV_FORCE=TRUE) it kills the tape backup application in
 779 #     order to allow the DR to continue.
 780 #
 781 # This script does not implement the postremove and undoremove commands
 782 # since there is nothing to cleanup after DR remove operation is
 783 # completed or failed. If any cleanup is needed after the DR removal
 784 # completed, postremove command needs to implemented. If any cleanup is
 785 # needed in the event of DR removal failure, undoremove command needs
 786 # to be implemented.
 787 #
 788
 789 use strict;
 790
 791 my ($cmd, %dispatch);
 792
 793 $cmd = shift(@ARGV);
 794
 795 # dispatch table for RCM commands
 796 %dispatch = (
 797     "scriptinfo"    =>      \&do_scriptinfo,
 798     "register"      =>      \&do_register,
 799     "resourceinfo"  =>      \&do_resourceinfo,
 800     "queryremove"   =>      \&do_preremove,
 801     "preremove"     =>      \&do_preremove
 802 );
 803
 804 if (defined($dispatch{$cmd})) {
 805     &{$dispatch{$cmd}};
 806 } else {
 807     exit (2);
 808 }
 809
 810 sub do_scriptinfo
 811 {
 812     print "rcm_script_version=1\en";
 813     print "rcm_script_func_info=Tape backup appl script for DR\en";
 814     exit (0);
 815 }
 816
 817 sub do_register
 818 {
 819     my ($dir, $f, $errmsg);
 820
 821     $dir = opendir(RMT, "/dev/rmt");
 822     if (!$dir) {
 823         $errmsg = "Unable to open /dev/rmt directory: $!";
 824         print "rcm_failure_reason=$errmsg\en";
 825         exit (1);
 826     }
 827
 828     while ($f = readdir(RMT)) {
 829         # ignore hidden files and multiple names for the same device
 830         if (($f !~ /^\./) && ($f =~ /^[0-9]+$/)) {
 831             print "rcm_resource_name=/dev/rmt/$f\en";
 832         }
 833
 834     }
 835
 836     closedir(RMT);
 837     exit (0);
 838 }
 839
 840 sub do_resourceinfo
 841 {
 842     my ($rsrc, $unit);
 843
 844     $rsrc = shift(@ARGV);
 845     if ($rsrc =~ /^\e/dev\e/rmt\e/([0-9]+)$/) {
 846         $unit = $1;
 847         print "rcm_resource_usage_info=Backup Tape Unit Number $unit\en";
 848         exit (0);
 849     } else {
 850         print "rcm_failure_reason=Unknown tape device!\en";
 851         exit (1);
 852     }
 853 }
 854
 855 sub do_preremove
 856 {
 857     my ($rsrc);
 858
 859     $rsrc = shift(@ARGV);
 860
 861     # check if backup application is using this resource
 862     # if (the backup application is not running on $rsrc) {
 863     # allow the DR to continue
 864     #        exit (0);
 865     #}
 866     #
 867     # If RCM_ENV_FORCE is FALSE deny the operation.
 868     # If RCM_ENV_FORCE is TRUE kill the backup application in order
 869     # to allow the DR operation to proceed
 870     #
 871     if ($ENV{RCM_ENV_FORCE} eq 'TRUE') {
 872         if ($cmd eq 'preremove') {
 873             # kill the tape backup application
 874         }
 875         exit (0);
 876     } else {
 877         #
 878         # indicate that the tape drive can not be released
 879         # since the device is being used for backup by the
 880         # tape backup application
 881         #
 882         print "rcm_failure_reason=tape backup in progress pid=...\en";
 883         exit (3);
 884
 885     }
 886 }
 887 .fi
 888 .in -2
 889
 890 .SH EXIT STATUS
 891 .LP
 892 A script must exit with following exit status values:
 893 .sp
 894 .ne 2
 895 .na
 896 \fB\fB0\fR\fR
 897 .ad
 898 .RS 5n
 899 Operation specified by the given RCM command has been executed successfully by
 900 the script. For \fBqueryremove\fR command it also means that the script can
 901 successfully release the resource.
 902 .RE
 903
 904 .sp
 905 .ne 2
 906 .na
 907 \fB\fB1\fR\fR
 908 .ad
 909 .RS 5n
 910 An error occurred while processing the RCM command. The script should provide
 911 the error message to RCM using the name-value pair \fBrcm_failure_reason\fR
 912 before exiting.
 913 .RE
 914
 915 .sp
 916 .ne 2
 917 .na
 918 \fB\fB2\fR\fR
 919 .ad
 920 .RS 5n
 921 The script does not support the given RCM command. A script must exit with this
 922 status if it cannot understand the given RCM command.
 923 .RE
 924
 925 .sp
 926 .ne 2
 927 .na
 928 \fB\fB3\fR\fR
 929 .ad
 930 .RS 5n
 931 Indicates that the script cannot release the resource for \fBpreremove\fR and
 932 \fBqueryremove\fR commands. The script should provide a message to RCM
 933 specifying the reason for not being able to release the resource using the
 934 name-value pair \fBrcm_failure_reason\fR before exiting.
 935 .RE
 936
 937 .SH ERRORS
 938 .LP
 939 If a script cannot successfully process an RCM command, it must supply to the
 940 RCM a message indicating the reason for failure by writing a name-value pair,
 941 in the form shown below, to stdout and exiting with the appropriate exit
 942 status.
 943 .sp
 944 .in +2
 945 .nf
 946 rcm_failure_reason=\fIfailure_reason\fR
 947 .fi
 948 .in -2
 949 .sp
 950
 951 .sp
 952 .LP
 953 where \fIfailure_reason\fR is a localized human readable message describing the
 954 reason for failure of the RCM command.
 955 .SH ATTRIBUTES
 956 .LP
 957 See \fBattributes\fR(5) for descriptions of the following attributes:
 958 .sp
 959
 960 .sp
 961 .TS
 962 box;
 963 c | c
 964 l | l .
 965 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 966 _
 967 Interface Stability     Evolving
 968 .TE
 969
 970 .SH SEE ALSO
 971 .LP
 972 \fBgettext\fR(1), \fBcfgadm\fR(1M), \fBcfgadm_scsi\fR(1M),
 973 \fBcfgadm_pci\fR(1M), \fBsyslog\fR(3C), \fBsignal.h\fR(3HEAD),
 974 \fBsyslog.conf\fR(4), \fBattributes\fR(5), \fBenviron\fR(5)
 975 .SH NOTES
 976 .LP
 977 RCM scripts are expected to properly handle all RCM commands that the script
 978 implements and to log all errors. Only root has permission to add or remove an
 979 RCM script. An ill-behaved RCM script can cause unexpected DR failures.
 980 .sp
 981 .LP
 982 RCM commands are invoked only for the resources whose subsystems participate
 983 within the RCM framework. Currently, not all subsystems participate within the
 984 RCM framework.