Reconfiguration Coordination Manager (RCM) Script Overview

The Reconfiguration Coordination Manager (RCM) is the framework that manages the dynamic removal of system components. By using RCM, you can register and release system resources in an orderly manner.

You can use the new RCM script feature to write your own scripts to shut down your applications, or to cleanly release the devices from your applications during dynamic reconfiguration. The RCM framework launches a script automatically in response to a reconfiguration request, if the request impacts the resources that are registered by the script.

You can also release resources from applications manually before you could dynamically remove the resource. Or, you could use the cfgadm command with the -f option to force a reconfiguration operation, but this option might leave your applications in an unknown state. Also, the manual release of resources from applications commonly causes errors.

The RCM script feature simplifies and better controls the dynamic reconfiguration process. By creating an RCM script, you can do the following:

• Automatically release a device when you dynamically remove a device. This process also closes the device if the device is opened by an application.

• Run site-specific tasks when you dynamically remove a device from the system.

What Is an RCM Script?

An RCM script is as follows:

• An executable shell script (Perl, sh, csh, or ksh) or binary program that the RCM daemon runs. Perl is the recommended language.

• A script that runs in its own address space by using the user ID of the script file owner.

• A script that is run by the RCM daemon when you use the cfgadm command to dynamically reconfigure a system resource.

What Can an RCM Script Do?

You can use an RCM script to release a device from an application when you dynamically remove a device. If the device is currently open, the RCM script also closes the device.

For example, an RCM script for a tape backup application can inform the tape backup application to close the tape drive or shut down the tape backup application.

How Does the RCM Script Process Work?

You can invoke a script as follows:

$ script-name command [args ...]

A script performs the following basic steps:

1. Takes the RCM command from command-line arguments.

2. Executes the command.

3. Writes the results to stdout as name-value pairs.

4. Exits with the appropriate exit status.

The RCM daemon runs one instance of a script at a time. For example, if a script is running, the RCM daemon does not run the same script until the first script exits.

RCM Script Commands

You must include the following RCM commands in an RCM script:

• scriptinfo – Gathers script information

• register – Registers interest in resources

• resourceinfo – Gathers resource information

You might include some or all of the following RCM commands:

• queryremove - Queries whether the resource can be released

• preremove - Releases the resource

• postremove - Provides post-resource removal notification

• undoremove - Undoes the actions done in preremove

For a complete description of these RCM commands, see rcmscript(4).

RCM Script Processing Environment

When you dynamically remove a device, the RCM daemon runs the following:

• The script's register command to gather the list of resources (device names) that are identified in the script.

• The script's queryremove/preremove commands prior to removing the resource if the script's registered resources are affected by the dynamic remove operation.

• The script's postremove command if the remove operation succeeds. However, if the remove operation fails, the RCM daemon runs the script's undoremove command.

RCM Script Tasks

The following sections describe the RCM script tasks for application developers and system administrators.

Application Developer RCM Script (Task Map)

The following task map describes the tasks for an application developer who is creating an RCM script.

System Administrator RCM Script (Task Map)

The following task map describes the tasks for a system administrator who is creating an RCM script to do site customization.

Naming an RCM Script

A script must be named as vendor,service where the following applies:

Installing or Removing an RCM Script

You must be superuser (root) to install or remove an RCM script. Use this table to determine where you should install your RCM script.

How to Install an RCM Script

1. Become superuser.

2. Copy the script to the appropriate directory as described in Table 27–1.

   For example:

   # cp SUNW,sample.pl /usr/lib/rcm/scripts

3. Change the user ID and the group ID of the script to the desired values.

   # chown user:group /usr/lib/rcm/scripts/SUNW,sample.pl

4. Send SIGHUP to the RCM daemon.

   # pkill -HUP -x -u root rcm_daemon

How to Remove an RCM Script

1. Become superuser.

2. Remove the script from the RCM script directory.

   For example:

   # rm /usr/lib/rcm/scripts/SUNW,sample.pl

3. Send SIGHUP to the RCM daemon.

   # pkill -HUP -x -u root rcm_daemon

How to Test an RCM Script

1. Set environment variables, such as RCM_ENV_FORCE, in the command-line shell before running your script.

   For example, in the Korn shell, use the following:

   $ export RCM_ENV_FORCE=TRUE

2. Test the script by running the script commands manually from the command line.

   For example:

   $ script-name scriptinfo $ script-name register $ script-name preremove resource-name $ script-name postremove resource-name

3. Make sure each RCM script command in your script prints appropriate output to stdout.

4. Install the script in the appropriate script directory.

   For more information, see How to Install an RCM Script.

5. Test the script by initiating a dynamic remove operation:

   For example, assume your script registers the device, /dev/dsk/c1t0d0s0. Try these commands.

   $ cfgadm -c unconfigure c1::dsk/c1t0d0 $ cfgadm -f -c unconfigure c1::dsk/c1t0d0 $ cfgadm -c configure c1::dsk/c1t0d0

   ---

   Caution –

   Make sure that you are familiar with these commands because they can alter the state of the system and can cause system failures.

   ---

Tape Backup RCM Script Example

This example illustrates how to use an RCM script for tape backups.

What the Tape Backup RCM Script Does

The tape backup RCM script performs the following steps:

1. Sets up a dispatch table of RCM commands.

2. Calls the dispatch routine that corresponds to the specified RCM command and exits with status 2 for unimplemented RCM commands.

3. Sets up the scriptinfo section:

   rcm_script_func_info=Tape backup appl script for DR

4. Registers all tape drives in the system by printing all tape drive device names to stdout.

   rcm_resource_name=/dev/rmt/$f

   If an error occurs, prints the error information to stdout.

   rcm_failure_reason=$errmsg

5. Sets up the resource information for the tape device.

   rcm_resource_usage_info=Backup Tape Unit Number $unit

6. Sets up the preremove information by checking if the backup application is using the device. If the backup application is not using the device, the dynamic reconfiguration operation continues. If the backup application is using the device, the script checks RCM_ENV_FORCE. If RCM_ENV_FORCE is set to FALSE, the script denies the dynamic reconfiguration operation and prints the following message:

   rcm_failure_reason=tape backup in progress pid=...

   If RCM_ENV_FORCE is set to TRUE, the backup application is stopped, and the reconfiguration operation proceeds.

Outcomes of the Tape Backup Reconfiguration Scenarios

Here are the various outcomes if you use the cfgadm command to remove a tape device without the RCM script.

• If you use the cfgadm command and the backup application is not using the tape device, the operation succeeds.

• If you use the cfgadm command and the backup application is using the tape device, the operation fails.

Here are the various outcomes if you use the cfgadm command to remove a tape device with the RCM script.

• If you use the cfgadm command and the backup application is not using the tape device, the operation succeeds.

• If you use the cfgadm command without the -f option and the backup application is using the tape device, the operation fails with an error message similar to the following:

  tape backup in progress pid=...

• If you use the cfgadm -f command and the backup application is using the tape device, the script stops the backup application and the cfgadm operation succeeds.

Example—Tape Backup RCM Script

#! /usr/bin/perl -w
   #
   # A sample site customization RCM script.
   #
   # When RCM_ENV_FORCE is FALSE this script indicates to RCM that it cannot
   # release the tape drive when the tape drive is being used for backup.
   #
   # When RCM_ENV_FORCE is TRUE this script allows DR removing a tape drive
   # when the tape drive is being used for backup by killing the tape
   # backup application.
   #
    
    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\n";
            print "rcm_script_func_info=Tape backup appl script for DR\n";
            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\n";
                 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\n";
                    }
                    
            }
    
            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\n";
           exit (0);
       } else {
           print "rcm_failure_reason=Unknown tape device!\n";
            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=...\n"
;
               exit (3);
            }
    }