JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Oracle Solaris 11.1 Administration: Devices and File Systems     Oracle Solaris 11.1 Information Library
search filter icon
search icon

Document Information

Preface

1.  Managing Removable Media (Tasks)

2.  Writing CDs and DVDs (Tasks)

3.  Managing Devices (Tasks)

4.  Dynamically Configuring Devices (Tasks)

Dynamic Reconfiguration and Hot-Plugging

Attachment Points

Detaching PCI or PCIe Adapter Cards

Attaching PCI or PCIe Adapter Cards

PCIe Hot-Plugging With the (hotplug) Command

Troubleshooting PCI Hot Plug Operations (hotplug)

SCSI Hot-Plugging With the cfgadm Command (Task Map)

SCSI Hot-Plugging With the cfgadm Command

How to Display Information About SCSI Devices

How to Unconfigure a SCSI Controller

How to Configure a SCSI Controller

How to Configure a SCSI Device

How to Disconnect a SCSI Controller

SPARC: How to Connect a SCSI Controller

SPARC: How to Add a SCSI Device to a SCSI Bus

SPARC: How to Replace an Identical Device on a SCSI Controller

SPARC: How to Remove a SCSI Device

Troubleshooting SCSI Configuration Problems

How to Resolve a Failed SCSI Unconfigure Operation

PCI or PCIe Hot-Plugging With the cfgadm Command (Task Map)

PCI or PCIe Hot-Plugging With the cfgadm Command

PCIe LED Indicator Behavior

How to Display PCI Slot Configuration Information

How to Remove a PCI Adapter Card

How to Add a PCI Adapter Card

Troubleshooting PCI Configuration Problems

SATA Hot-Plugging With the cfgadm Command

How to Unconfigure a SATA Device

How to Configure a SATA Device

Reconfiguration Coordination Manager (RCM) Script Overview

What Is an RCM Script?

What Can an RCM Script Do?

How Does the RCM Script Process Work?

RCM Script Commands

RCM Script Processing Environment

RCM Script Tasks

Application Developer RCM Script (Task Map)

System Administrator RCM Script (Task Map)

Naming an RCM Script

Installing or Removing an RCM Script

How to Install an RCM Script

How to Remove an RCM Script

How to Test an RCM Script

Tape Backup RCM Script Example

What the Tape Backup RCM Script Does

Outcomes of the Tape Backup Reconfiguration Scenarios

Example--Tape Backup RCM Script

5.  Managing USB Devices (Tasks)

6.  Using InfiniBand Devices (Overview/Tasks)

7.  Managing Disks (Overview)

8.  Managing Disk Use (Tasks)

9.  Administering Disks (Tasks)

10.  Setting Up Disks (Tasks)

11.  Configuring Storage Devices With COMSTAR (Tasks)

12.  Configuring and Managing the Oracle Solaris Internet Storage Name Service (iSNS)

13.  The format Utility (Reference)

14.  Managing File Systems (Overview)

15.  Creating and Mounting File Systems (Tasks)

16.  Configuring Additional Swap Space (Tasks)

17.  Copying Files and File Systems (Tasks)

18.  Managing Tape Drives (Tasks)

Index

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.

Task
Description
For Instructions
1. Identify the resources your application uses.
Identify the resources (device names) your application uses that you could potentially dynamically remove.
2. Identify the commands to release the resource.
Identify the commands for notifying the application to cleanly release the resource from the application.
Application documentation
3. Identify the commands for post-removal of the resource.
Include the commands for notifying the application of the resource removal.
4. Identify the commands if the resource removal fails.
Include the commands for notifying the application of the available resource.
5. Write the RCM script.
Write the RCM script based on the information identified in tasks 1-4.
6. Install the RCM script.
Add the script to the appropriate script directory.
7. Test the RCM script
Test the script by running the script commands manually and by initiating a dynamic reconfiguration operation.

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.

Task
Description
For Instructions
1. Identify the resources to be dynamically removed.
Identify the resources (device names) to be potentially removed by using the cfgadm -l command.
2. Identify the applications to be stopped.
Identify the commands for stopping the applications cleanly.
Application documentation
3. Identify the commands for pre-removal and post-removal of the resource.
Identify the actions to be taken before and after the resource is removed.
4. Write the RCM script.
Write the RCM script based on the information identified in tasks 1-3.
5. Install the RCM script.
Add the script to the appropriate script directory.
6. Test the RCM script.
Test the script by running the script commands manually and by initiating a dynamic reconfiguration operation.

Naming an RCM Script

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

vendor

Is the stock symbol of the vendor that provides the script, or any distinct name that identifies the vendor.

service

Is the name of the service that the script represents.

Installing or Removing an RCM Script

You must be an administrator to install or remove an RCM script. Use this table to determine where you should install your RCM script.

Table 4-1 RCM Script Directories

Directory Location
Script Type
/etc/rcm/scripts
Scripts for specific systems
/usr/platform/`uname -i`/lib/rcm/scripts
Scripts for a specific hardware implementation
/usr/platform/`uname -m`/lib/rcm/scripts
Scripts for a specific hardware class
/usr/lib/rcm/scripts
Scripts for any hardware

How to Install an RCM Script

  1. Become an administrator.
  2. Copy the script to the appropriate directory.

    See Table 4-1.

    For example:

    # cp ABC,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/ABC,sample.pl
  4. Send SIGHUP to the RCM daemon.
    # pkill -HUP -x -u root rcm_daemon

How to Remove an RCM Script

  1. Become an administrator.
  2. Remove the script from the RCM script directory.

    For example:

    # rm /usr/lib/rcm/scripts/ABC,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 that 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

    Caution - Make sure that you are familiar with these commands because they can alter the state of the system and 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, the script 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:

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

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);
            }
    }